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
logEvent
methodThe 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:
- (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 parametersNSDictionary
- The third argument (
completionHandler
) is an optional completion handler (useful for Handling event submission success/failure)
Note
eventValues
(second argument) must be a validNSDictionary
. 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:
[[AppsFlyerLib shared] logEvent: AFEventAddToWishlist withValues: @{
AFEventParamPrice: @20,
AFEventParamContentId: @"123456"
}]
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:
[[AppsFlyerLib shared] logEvent: AFEventContentView withValues: @{
AFEventParamContentId: <ITEM_SKU>,
AFEventParamContentType: <ITEM_TYPE>,
AFEventParamPrice: <ITEM_PRICE>
}]
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
[[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);
}
}];
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
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'supdateConversionValue
even ifstart
wasn't called orisStopped
is set totrue
(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
[[AppsFlyerLib shared] logEvent: AFEventPurchase
withValues:@{
AFEventParamContentId:@"1234567",
AFEventParamContentType : @"category_a",
AFEventParamRevenue: @200,
AFEventParamCurrency:@"USD"
}];
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:
[[AppsFlyerLib shared] logEvent: AFEventPurchase
withValues:@{
AFEventParamRevenue: @200,
AFEventParamCurrency:@"USD"
}];
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:
[[AppsFlyerLib shared] logEvent: @"cancel_purchase"
withValues:@{
AFEventParamContentId:@"1234567",
AFEventParamContentType : @"category_a",
AFEventParamRevenue: @-1.99,
AFEventParamCurrency:@"USD"
}];
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. The validateAndLogInAppPurchase
method takes care of validating and logging the purchase event.
Note
The legacy function
validateAndLogInAppPurchase
can be replaced by the newer and fully automatic purchase SDK connector. To learn how to integrate the connector, see in Github iOS purchase SDK connector
Purchase validation using validateAndLogInAppPurchase
validateAndLoginInAppPurchase
takes these arguments:
- (void) validateAndLogInAppPurchase:(NSString *) productIdentifier,
price:(NSString *) price
currency:(NSString *) currency
transactionId:(NSString *) tranactionId
additionalParameters:(NSDictionary *) params
success:(void (^)(NSDictionary *response)) successBlock
failure:(void (^)(NSError *error, id reponse)) failedBlock;
validateAndLog(inAppPurchase: String?,
price: String?,
currency: String?,
transactionId: String?,
additionalParameters: [AnyHashable : Any]?,
success: ([AnyHashable : Any]) -> Void)?,
failure: ((Error?, Any?) -> Void)?)
Upon successful validation, a NSDictionary
is returned with the receipt validation data (provided by Apple servers).
Note
Calling
validateAndLogInAppPurchase
generates anaf_purchase
in-app event upon successful validation. Sending this event yourself creates duplicate event reporting.
Example: Validate in-app purchase
[[AppsFlyerLib shared] validateAndLogInAppPurchase:@"ProductIdentifier" price:@"price"
currency:@"USD"
transactionId:@"transactionID"
additionalParameters:@{@"test": @"val" , @"test1" : @"val 1"}
success:^(NSDictionary *result){
NSLog(@"Purchase succeeded And verified! response: %@", result[@"receipt"]);
} failure:^(NSError *error, id response) {
NSLog(@"response = %@", response);
if([response isKindOfClass:[NSDictionary class]]) {
if([response[@"status"] isEqualToString:@"in_app_arr_empty"]){
// retry with 'SKReceiptRefreshRequest' because
// Apple has returned an empty response
// <YOUR CODE HERE>
}
} else {
//handle other errors
return;
}
}];
AppsFlyerLib.shared().validateAndLogInAppPurchase (
inAppPurchase: "productIdentifier",
price: "price",
currency: "currency",
transactionId: "transactionId",
additionalParameters: [:],
success: {
guard let dictionary = $0 as? [String:Any] else { return }
dump(dictionary)
},
failure: { error, result in
guard let emptyInApp = result as? [String:Any],
let status = emptyInApp["status"] as? String,
status == "in_app_arr_empty" else {
// Try to handle other errors
return
}
})
Testing purchase validation in Sandbox mode
To test purchase validation using a sandboxed environment, add the following code:
[AppsFlyerLib shared].useReceiptValidationSandbox = YES;
AppsFlyerLib.shared().useReceiptValidationSandbox = true
Note
This code must be removed from your production builds.
Validating an in-app purchase automatically generates and sends an in-app purchase event to AppsFlyer. Its eventValues
will look something like this:
{
"some_parameter": "some_value", // from additional_event_values
"af_currency": "USD", // from currency
"af_content_id" :"test_id", // from purchase
"af_revenue": "10", // from revenue
"af_quantity": "1", // from purchase
"af_validated": true // flag that AF verified the 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 |
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 |
Updated 19 days ago