In-app events

Overview

In-app events provide insights into how users interact with your app. The AppsFlyer SDK lets you log these interactions.

Anatomy of an event

In-app events consist of two parts:

• Event name: the unique event identifier. It's usually how marketers see the event in the dashboard.
• Event values: an object made up of key-value pairs called event parameters, which provide additional context about the event.

Event names and parameters can be predefined or custom.

👍

Tip

Quickly define and generate in-app events code for all major platforms using the in-app event generator tool.

Predefined events and parameters are exposed as SDK constants (see Event constants below), prefixed with af_. Use the constants instead of raw strings: it avoids naming mistakes, and changes to the underlying names stay transparent to you.

Custom event names and parameters are user-defined and describe scenarios specific to your app.

🚧

Attention

To avoid confusion with predefined events, don't prefix custom event names with af_.

Valid custom event names: up to 100 characters, non-English characters supported.

Valid custom event parameters: up to 1000 characters (longer values may be truncated). Pricing and revenue values should use digits and decimals only (e.g. 5 or 5.2), up to 5 digits after the decimal point.

Before you begin

You must integrate the SDK.

Integrate In-App Events with our SDK wizard

Let's go

Logging in-app events

The SDK lets you log user actions happening in the context of your app. These are commonly referred to as in-app events.

The logEvent method

The logEvent method lets you log in-app events and send them to AppsFlyer for processing.

To access the logEvent method, import AppsFlyerLib:

import com.appsflyer.AppsFlyerLib;

import com.appsflyer.AppsFlyerLib

To access predefined event constants, import AFInAppEventType and AFInAppEventParameterName:

import com.appsflyer.AFInAppEventType; // Predefined event names
import com.appsflyer.AFInAppEventParameterName; // Predefined parameter names

import com.appsflyer.AFInAppEventType // Predefined event names
import com.appsflyer.AFInAppEventParameterName // Predefined parameter names

logEvent takes 4 arguments:

void logEvent(Context context,
              java.lang.String eventName,
              java.util.Map<java.lang.String,java.lang.Object> eventValues,
              AppsFlyerRequestListener listener)

• The first argument (context) is the Application/Activity Context
• The second argument (eventName) is the In-app event name
• The third argument (eventValues) is the event parameters Map
• The fourth argument (listener) is an optional AppsFlyerRequestListener (useful for Handling event submission success/failure)

Example: Send "add to wishlist" event

For example, to log that a user added an item to their wishlist:

Map<String, Object> eventValues = new HashMap<String, Object>();
eventValues.put(AFInAppEventParameterName.PRICE, 1234.56);
eventValues.put(AFInAppEventParameterName.CONTENT_ID,"1234567");

AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    AFInAppEventType.ADD_TO_WISHLIST , eventValues);

val eventValues = HashMap<String, Any>() 
eventValues.put(AFInAppEventParameterName.PRICE, 1234.56)
eventValues.put(AFInAppEventParameterName.CONTENT_ID,"1234567")

AppsFlyerLib.getInstance().logEvent(getApplicationContext() ,
                                    AFInAppEventType.ADD_TO_WISHLIST , eventValues)

In the above logEvent invocation:

• The event name is AFInAppEventType.ADD_TO_WISHLIST
• The event value is a Map containing these event parameters:
  • AFInAppEventParameterName.PRICE: The price that's associated with the event
  • AFInAppEventParameterName.CONTENT_ID: The identifier of the added item

Understanding event structure definitions

Before implementing an event, it helps to have a clear event structure definition. For example, a definition for an af_content_view event on an eCommerce app:

• The event name is the value you pass as the event name argument to logEvent.
• The event parameters list what to pass alongside it.
• Parameter values clarify what each parameter should contain.
• Where/When describes the trigger point in your app.

Implementing event structure definitions

Based on the example definition above, the event should be implemented as follows:

Map<String, Object> eventValues = new HashMap<String, Object>();
eventValues.put(AFInAppEventParameterName.PRICE, <ITEM_PRICE>);
eventValues.put(AFInAppEventParameterName.CONTENT_TYPE, <ITEM_TYPE>);
eventValues.put(AFInAppEventParameterName.CONTENT_ID, <ITEM_SKU>);

AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    AFInAppEventType.CONTENT_VIEW, eventValues);

val eventValues = HashMap<String, Any>() 
eventValues.put(AFInAppEventParameterName.PRICE, <ITEM_PRICE>)
eventValues.put(AFInAppEventParameterName.CONTENT_TYPE, <ITEM_TYPE>)
eventValues.put(AFInAppEventParameterName.CONTENT_ID, <ITEM_SKU>)

AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    AFInAppEventType.CONTENT_VIEW, eventValues)

Handling event submission success and failure

You can provide logEvent with a AppsFlyerRequestListener object when recording in-app events. The handler allows you to define logic for two scenarios:

• An in-app event is recorded successfully
• An error occurred when recording the in-app event

AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    AFInAppEventType.PURCHASE,
                                    eventValues,
                                    new AppsFlyerRequestListener() {
                    @Override
                    public void onSuccess() {
                        Log.d(LOG_TAG, "Event sent successfully");
                    }
                    @Override
                    public void onError(int i, @NonNull String s) {
                        Log.d(LOG_TAG, "Event failed to be sent:\n" +
                                "Error code: " + i + "\n"
                                + "Error description: " + s);
                    }
                });

AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    AFInAppEventType.PURCHASE,
                                    eventValues,
                                    object : AppsFlyerRequestListener {
            override fun onSuccess() {
                Log.d(LOG_TAG, "Event sent successfully")
            }
            override fun onError(errorCode: Int, errorDesc: String) {
                Log.d(LOG_TAG, "Event failed to be sent:\n" +
                        "Error code: " + errorCode + "\n"
                        + "Error description: " + errorDesc)
            }
        })

In the event that an error occurs when recording the in-app event, an error code and string description are provided, as indicated in the table that follows.

Recording offline events

The SDK can cache in-app events that occur when no internet connection is available:

• It sends events to AppsFlyer and waits for a response.
• If it doesn't receive a 200 response, the events are cached.
• Once the next 200 response arrives, cached events are re-sent, one network request per event (unbatched).
• The cache holds up to 40 events. Anything beyond that, until the next successful response, is discarded.

Logging events before calling start

If you initialized the SDK but didn't call start, the SDK will cache in-app events until start is invoked.

If there are multiple events in the cache, they are sent to the server one after another (unbatched, one network request per event).

Logging revenue

📘

Note

For events with revenue, including in-app purchases, subscriptions, and ad revenue events, AppsFlyer customers with an ROI360 subscription should avoid using the AFInAppEventParameterName.REVENUE(af_revenue) parameter in their in-app events. Doing so can result in duplicate revenue being reported. Instead, they should utilize the purchase connector and the ad revenue SDK API.

You can send revenue with any in-app event. Use the AFInAppEventParameterName.REVENUE event parameter to include revenue in the in-app event. You can populate it with any numeric value, positive or negative.

The revenue value should not contain comma separators, currency signs, or text. A revenue event should be similar to 1234.56, for example.

Example: Purchase event with revenue

Map<String, Object> eventValues = new HashMap<String, Object>();
eventValues.put(AFInAppEventParameterName.CONTENT_ID, <ITEM_SKU>);
eventValues.put(AFInAppEventParameterName.CONTENT_TYPE, <ITEM_TYPE>);
eventValues.put(AFInAppEventParameterName.REVENUE, 200);

AppsFlyerLib.getInstance().logEvent(getApplicationContext(), 
                                    AFInAppEventType.PURCHASE, eventValues);

val eventValues = HashMap<String, Any>() 
eventValues.put(AFInAppEventParameterName.CONTENT_ID, <ITEM_SKU>)
eventValues.put(AFInAppEventParameterName.CONTENT_TYPE, <ITEM_TYPE>)
eventValues.put(AFInAppEventParameterName.REVENUE, 200)

AppsFlyerLib.getInstance().logEvent(getApplicationContext(), 
                                    AFInAppEventType.PURCHASE, eventValues)

The purchase event above has $200 in revenue, appearing as revenue in the dashboard.

📘

Note

Do not add currency symbols to the revenue value.

Configuring revenue currency

You can set the currency code for an event's revenue by using the af_currency predefined event parameter:

Map<String, Object> eventValues = new HashMap<String, Object>();
eventValues.put(AFInAppEventParameterName.CURRENCY, "USD");
eventValues.put(AFInAppEventParameterName.REVENUE, <TRANSACTION_REVENUE>);
AppsFlyerLib.getInstance().logEvent(getApplicationContext(), 
                                    AFInAppEventType.PURCHASE, eventValues);

val eventValues = HashMap<String, Any>() 
eventValues.put(AFInAppEventParameterName.REVENUE, <TRANSACTION_REVENUE>)
eventValues.put(AFInAppEventParameterName.CURRENCY,"USD")
AppsFlyerLib.getInstance().logEvent(getApplicationContext() , AFInAppEventType.PURCHASE , eventValues)

• The currency code should be a 3 character ISO 4217 code
• The default currency is USD

To learn about currency settings, display, and currency conversion, see our guide on revenue currency.

Logging net revenue

To report net revenue alongside gross revenue, add a custom parameter with the key af_net_revenue to the event values. The value represents net revenue according to your own business logic, for example revenue after store fees and/or taxes, gross margin, or revenue after service fees.

There is no predefined SDK constant for this parameter, so pass the string key directly. Follow the same formatting rules as af_revenue, and the same currency rules (currency via af_currency, default USD).

Map<String, Object> eventValues = new HashMap<String, Object>();
eventValues.put(AFInAppEventParameterName.REVENUE, 200);   // gross
eventValues.put("af_net_revenue", 140);                    // net (custom key)
eventValues.put(AFInAppEventParameterName.CURRENCY, "USD");

AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    AFInAppEventType.PURCHASE, eventValues);

val eventValues = HashMap<String, Any>()
eventValues.put(AFInAppEventParameterName.REVENUE, 200)          // gross
eventValues.put("af_net_revenue", 140)                           // net (custom key)
eventValues.put(AFInAppEventParameterName.CURRENCY, "USD")

AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    AFInAppEventType.PURCHASE, eventValues)

📘

Note

For apps with ROI360 store revenue enabled, af_net_revenue is populated automatically on the in-app purchase and subscription events recorded by ROI360 store revenue, so you do not need to send it for those events.

Logging negative revenue

There may be situations where you want to record negative revenue. For example, a user receives a refund or cancels a subscription.

To log negative revenue:

Map<String, Object> eventValues = new HashMap<String, Object>();
eventValues.put(AFInAppEventParameterName.REVENUE, -1234.56);
eventValues.put(AFInAppEventParameterName.CONTENT_ID,"1234567");
AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    "cancel_purchase",
                                    eventValues);

val eventValues = HashMap<String, Any>() 
eventValues.put(AFInAppEventParameterName.REVENUE, -1234.56)
eventValues.put(AFInAppEventParameterName.CONTENT_ID,"1234567")
AppsFlyerLib.getInstance().logEvent(getApplicationContext(),
                                    "cancel_purchase",
                                    eventValues)

📘

Note

Notice the following in the code above:

• The revenue value is preceded by a minus sign
• The event name is a custom event name called "cancel_purchase" - it helps you easily identify negative revenue events in the dashboard and raw data reports

Validating purchases

AppsFlyer provides server verification for in-app purchases. For more information see Validate and log purchase

Event constants

Predefined event names

To use the following constants, import com.appsflyer.AFInAppEventType:

import com.appsflyer.AFInAppEventType;

import com.appsflyer.AFInAppEventType

Predefined event name constants follow a AFInAppEventType.EVENT_NAME naming convention. For example, AFInAppEventType.ADD_TO_CART

Predefined event parameters

To use the following constants, import AFInAppEventParameterName:

import com.appsflyer.AFInAppEventParameterName;

import com.appsflyer.AFInAppEventParameterName

Predefined event parameter constants follow a AFInAppEventParameterName.PARAMETER_NAME naming convention. For example, AFInAppEventParameterName.CURRENCY