In-app events

Learn how to work with in-app events in the iOS SDK.

Overview

This document is a guide on implementing in-app events in the iOS SDK. For an introduction to in-app events for developers, see in-app events.

Before you begin

You must integrate the SDK.

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.

AppsFlyerLib exposes logEvent, predefined event name constants and predefined event parameter constants.

logEvent takes 3 arguments:

Objective-C

- (void)logEventWithEventName:(NSString *)eventName
        eventValues:(NSDictionary<NSString * , id> * _Nullable)eventValues
        completionHandler:(void (^ _Nullable)(NSDictionary<NSString *, id> * _Nullable dictionary, NSError * _Nullable error))completionHandler;

• The first argument (eventName) is the event name
• The second argument (eventValues) is the event parameters NSDictionary
• The third argument (completionHandler) is an optional completion handler (useful for Handling event submission success/failure)

📘

Note

eventValues (second argument) must be a valid NSDictionary. For more information, see Foundation JSONSerialization.

Example: Send "add to wishlist" event

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

Objective-C

[[AppsFlyerLib shared]  logEvent: AFEventAddToWishlist withValues: @{
    AFEventParamPrice: @20,
    AFEventParamContentId: @"123456"
}]

Swift

AppsFlyerLib.shared().logEvent(AFEventAddToWishlist,
  withValues: [
     AFEventParamPrice: 20,
     AFEventParamContentId: "123456"
]);

In the above logEvent invocation:

• The event name is AFEventAddToWishlist
• The event value is a NSDictionary containing these event parameters:
  • AFEventParamPrice: The item price the user added to their wishlist
  • AFEventParamContentId: The identifier of the added item

Implementing in-app event definitions

Based on the example definition provided in Understanding event structure definitions, the event should be implemented as follows:

Objective-C

[[AppsFlyerLib shared]  logEvent: AFEventContentView withValues: @{
    AFEventParamContentId: <ITEM_SKU>,
    AFEventParamContentType: <ITEM_TYPE>,
    AFEventParamPrice: <ITEM_PRICE>
}]

Swift

AppsFlyerLib.shared().logEvent(AFEventAddToCart,
  withValues: [
    AFEventParamContent: <ITEM_NAME>
    AFEventParamContentId: <ITEM_SKU>
    AFEventParamPrice: <ITEM_PRICE>
]);

Handling event submission success and failure

You can pass a completionHandler to logEvent when recording in-app events. The handler allows you to define logic for two scenarios:

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

Objective-C

[[AppsFlyerLib shared] logEventWithEventName:AFEventPurchase
        eventValues: @{
          AFEventParamRevenue: @200,
          AFEventParamCurrency: @"USD",
          AFEventParamQuantity: @2,
          AFEventParamContentId: @"092",
          AFEventParamReceiptId: @"9277"
        }
        completionHandler:^(NSDictionary<NSString *,id> * _Nullable dictionary, NSError * _Nullable error){
            if(dictionary != nil) {
                NSLog(@"In app callback success:");
                for(id key in dictionary){
                    NSLog(@"Callback response: key=%@ value=%@", key, [dictionary objectForKey:key]);
                }
            }
            if(error != nil) {
                NSLog(@"In app callback error:", error);
            }
    }];

Swift

AppsFlyerLib.shared().logEvent(name: AFEventAddToWishlist,
          values: [
             AFEventParamPrice: 20,
             AFEventParamContentId: "123456"
          ],
          completionHandler: { (response: [String : Any]?, error: Error?) in
            if let response = response {
              print("In app event callback Success: ", response)
            }
            if let error = error {
              print("In app event callback ERROR:", error)
            }
          });

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.

Error code	Description (NSError)
10	"Event timeout. Check 'minTimeBetweenSessions' param"
11	"Skipping event because 'isStopTracking' enabled"
40	Network error: Error description comes from iOS
41	"No dev key"
50	"Status code failure" + actual response code from the server

Recording offline events

The SDK can record events that occur when no internet connection is available. See Offline in-app events for details.

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

📘

Note

If the SDK is initialized, logEvent invocations will call SKAdNetwork's updateConversionValue even if start wasn't called or isStopped is set to true (in both SDK and S2S modes).

Logging revenue

af_revenue is the only event parameter that AppsFlyer counts as real revenue in the dashboard and reports.
You can send revenue with any in-app event. Use the AFEventParameterRevenue constant 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

Objective-C

[[AppsFlyerLib shared] logEvent: AFEventPurchase 
withValues:@{
	AFEventParamContentId:@"1234567",
	AFEventParamContentType : @"category_a",
	AFEventParamRevenue: @200,
	AFEventParamCurrency:@"USD"
}];

Swift

AppsFlyerLib.shared().logEvent(AFEventPurchase, 
withValues: [
	AFEventParamContentId:"1234567",
	AFEventParamContentType : "category_a",
	AFEventParamRevenue: 200,
	AFEventParamCurrency:"USD"
]);

📘

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:

Objective-C

[[AppsFlyerLib shared] logEvent: AFEventPurchase
withValues:@{
	AFEventParamRevenue: @200,
	AFEventParamCurrency:@"USD"
}];

Swift

AppsFlyerLib.shared().logEvent(AFEventPurchase, 
withValues: [
	AFEventParamRevenue: 200,
	AFEventParamCurrency:"USD"
]);

• 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 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:

Objective-C

[[AppsFlyerLib shared] logEvent: @"cancel_purchase" 
withValues:@{
	AFEventParamContentId:@"1234567",
	AFEventParamContentType : @"category_a",
	AFEventParamRevenue: @-1.99,
	AFEventParamCurrency:@"USD"
}];

Swift

AppsFlyerLib.shared().logEvent("cancel_purchase", 
withValues: [
	AFEventParamContentId:"1234567",
	AFEventParamContentType : "category_a",
	AFEventParamRevenue: -1.99,
	AFEventParamCurrency:"USD"
]);

Notice the following in the code above:

• The revenue value is preceded by a minus sign
• The event name is a custom event called cancel_purchase - that's how the marketer identifies 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

Predefined event name constants follow a AFEventEventName naming convention. For example, AFEventAddToCart.

Event name	iOS constant name
"af_level_achieved"	AFEventLevelAchieved
"af_add_payment_info"	AFEventAddPaymentInfo
"af_add_to_cart"	AFEventAddToCart
"af_add_to_wishlist"	AFEventAddToWishlist
"af_complete_registration"	AFEventCompleteRegistration
"af_tutorial_completion"	AFEventTutorial_completion
"af_initiated_checkout"	AFEventInitiatedCheckout
"af_purchase"	AFEventPurchase
"af_rate"	AFEventRate
"af_search"	AFEventSearch
"af_spent_credits"	AFEventSpentCredits
"af_achievement_unlocked"	AFEventAchievementUnlocked
"af_content_view"	AFEventContentView
"af_list_view"	AFEventListView
"af_travel_booking"	AFEventTravelBooking
"af_share"	AFEventShare
"af_invite"	AFEventInvite
"af_login"	AFEventLogin
"af_re_engage"	AFEventReEngage
"af_update"	AFEventUpdate
"af_opened_from_push_notification"	AFEventOpenedFromPushNotification
"af_location_coordinates"	AFEventLocation
"af_customer_segment"	AFEventCustomerSegment
"af_subscribe"	AFEventSubscribe
"af_start_trial"	AFEventStartTrial
"af_ad_click"	AFEventAdClick
"af_ad_view"	AFEventAdView

Predefined event parameters

Predefined event parameter constants follow a AFEventParamParameterName naming convention. For example, AFEventParamRevenue.

Event parameter name	iOS constant name	Type
"af_content"	AFEventParamContent	String
"af_achievement_id"	AFEventParamAchievementId	String
"af_level"	AFEventParamLevel	String
"af_score"	AFEventParamScore	String
"af_success"	AFEventParamSuccess	String
"af_price"	AFEventParamPrice	float
"af_content_type"	AFEventParamContentType	String
"af_content_id"	AFEventParamContentId	String
"af_content_list"	AFEventParamContentList	String[]
"af_currency"	AFEventParamCurrency	String
"af_quantity"	AFEventParamQuantity	int
"af_registration_method"	AFEventParamRegistrationMethod	String
"af_payment_info_available"	AFEventParamPaymentInfoAvailable	String
"af_max_rating_value"	AFEventParamMaxRatingValue	String
"af_rating_value"	AFEventParamRatingValue	String
"af_search_string"	AFEventParamSearchString	String
"af_date_a"	AFEventParamDateA	String
"af_date_b"	AFEventParamDateB	String
"af_destination_a"	AFEventParamDestinationA	String
"af_destination_b"	AFEventParamDestinationB	String
"af_description"	AFEventParamDescription	String
"af_class"	AFEventParamClass	String
"af_event_start"	AFEventParamEventStart	String
"af_event_end"	AFEventParamEventEnd	String
"af_lat"	AFEventParamLat	String
"af_long"	AFEventParamLong	String
"af_customer_user_id"	AFEventParamCustomerUserId	String
"af_validated"	AFEventParamValidated	boolean
"af_revenue"	AFEventParamRevenue	float
"af_projected_revenue"	AFEventProjectedParamRevenue	float
"af_receipt_id"	AFEventParamReceiptId	String
"af_tutorial_id"	AFEventParamTutorialId	String
"af_virtual_currency_name"	AFEventParamVirtualCurrencyName
"af_deep_link"	AFEventParamDeepLink	String
"af_old_version"	AFEventParamOldVersion	String
"af_new_version"	AFEventParamNewVersion	String
"af_review_text"	AFEventParamReviewText	String
"af_coupon_code"	AFEventParamCouponCode	String
"af_order_id"	AFEventParamOrderId	String
"af_param_1"	AFEventParam1	String
"af_param_2"	AFEventParam2	String
"af_param_3"	AFEventParam3	String
"af_param_4"	AFEventParam4	String
"af_param_5"	AFEventParam5	String
"af_param_6"	AFEventParam6	String
"af_param_7"	AFEventParam7	String
"af_param_8"	AFEventParam8	String
"af_param_9"	AFEventParam9	String
"af_param_10"	AFEventParam10	String
"af_departing_departure_date"	AFEventParamDepartingDepartureDate	String
"af_returning_departure_date"	AFEventParamReturningDepartureDate	String
"af_destination_list"	AFEventParamDestinationList	String[]
"af_city"	AFEventParamCity	String
"af_region"	AFEventParamRegion	String
"af_country"	AFEventParamCountry	String
"af_departing_arrival_date"	AFEventParamDepartingArrivalDate	String
"af_returning_arrival_date"	AFEventParamReturningArrivalDate	String
"af_suggested_destinations"	AFEventParamSuggestedDestinations	String[]
"af_travel_start"	AFEventParamTravelStart	String
"af_travel_end"	AFEventParamTravelEnd	String
"af_num_adults"	AFEventParamNumAdults	String
"af_num_children"	AFEventParamNumChildren	String
"af_num_infants"	AFEventParamNumInfants	String
"af_suggested_hotels"	AFEventParamSuggestedHotels	String[]
"af_user_score"	AFEventParamUserScore	String
"af_hotel_score"	AFEventParamHotelScore	String
"af_purchase_currency"	AFEventParamPurchaseCurrency	String
"af_preferred_neighborhoods"	AFEventParamPreferredNeighborhoods //array of string	String[]
"af_preferred_num_stops"	AFEventParamPreferredNumStops	String
"af_adrev_ad_type"	AFEventParamAdRevenueAdType	String
"af_adrev_network_name"	AFEventParamAdRevenueNetworkName	String
"af_adrev_placement_id"	AFEventParamAdRevenuePlacementId	String
"af_adrev_ad_size"	AFEventParamAdRevenueAdSize	String
"af_adrev_mediated_network_name"	AFEventParamAdRevenueMediatedNetworkName	String
"af_preferred_price_range"	AFEventParamPreferredPriceRange	int[] - basically a tuple(min,max) but we'll use array of int and use two values
"af_preferred_star_ratings"	AFEventParamPreferredStarRatings	int[] - basically a tuple(min,max) but we'll use array of int and use two values