Professional Documents
Culture Documents
Integration Guide
Version 2.5.3.16.2
Table of Contents
1. Introduction
2. Whats New in this Version?
3. Embed the SDK into Your Application (Mandatory)
4. SDK Initialization & Installation Event (Minimum Requirement for Tracking)
5. In-App Events Tracking API (Optional)
6. Advanced Integration
6.1 Set Currency Code (Optional)
6.2 Get AppsFlyer Unique ID (Optional)
6.3 Set Customer User ID (Optional)
6.4 Get Conversion Data (Optional)
6.5 Set User Email (Optional)
6.6 Reporting Deeplinks for Re-Targeting Attribution (Optional)
6.7 In-App Purchase Receipt Validation (Optional)
6.8 Set HTTPS (Optional)
6.9 End User Opt-out (Optional)
6.10 Explicit opt-out from ID for Advertisers IDFA/IFA (Optional)
7. Testing the SDK Integration
Appendix A: AppsFlyer Rich In-App Events
support@appsflyer.com
www.appsflyer.com
1. Introduction
AppsFlyer'sSDKprovidesappinstallationandeventtrackingfunctionality.Ourgoalistoprovideyouwithan
SDKthatishighlyrobust(7+billionSDKinstallationstodate),secure,lightweightandverysimpleforthe
developertoembed.
Youcantrackinstalls,updatesandsessions(byfollowingthemandatorystepsbelow),
andyoucanalsotrackadditionalinappeventsbeyondappinstalls(includinginapppurchases,game
levels,etc.)toevaluateROIanduserengagementlevels.
ThemandatorystepsareexplainedinSection3andSection4below,followedbyadditionaloptional
features.
TheiOSSDKiscompatiblewithalliOSdevices(iPhone,iPod,iPad)withiOSversion6.0andabove.
2.1Added
setUserEmails
APItoenablereportingofthedevicesassociatedemailaccounts(section6.5)
ThesimplestwaytointegratetheiOSSDKisusing
cocoapods
:
Addthefollowinglinetoyourpodfile:
pod 'AppsFlyer-SDK'
Ifyoudontusecocoapods,followthestepsbelow:
Addtheheaderandlibfilestoyourproject.
AppsFlyerSDKcomponents(
libAppsFlyerLib.a&AppsFlyerTracker.h
)areavailable
here
.
AddtheAppsFlyerheaderimport:
#import "AppsFlyerTracker.h"
Addthe
AdSupport.framework
toyourprojectandsetitasOptional.Youcanfindthe
submissioninstructions
here
.
Note:AppsFlyerwillcollectIDFAonlyifyouinclude
AdSupport.framework
Addthe
iAd.framework
toyourproject.
Notethatthisistheminimumrequirementtostarttrackingyourappinstalls.
YouneedtoinitializetheSDKonthefirstlaunchoftheapp.PleasemakesurethattheSDKisinitialized
beforesendingthetrackingeventbelow.
4.1InordertoinitializetheSDK,addthefollowingcodetoyour
didFinishLaunchingWithOptions
function:
support@appsflyer.com
www.appsflyer.com
Replace[
Dev_Key]
withyourown
Dev_Key
(accessiblefromyouraccount,seeSettings>>Integratethe
SDKinto...intheAppsFlyerdashboard).
4.2Addthefollowingcodetoyour
AppDelegate.m
sourcefileat
applicationDidBecomeActive
function:
#import "AppsFlyerTracker.h"
-(void)applicationDidBecomeActive:(UIApplication *)application
{
// Track Installs, updates & sessions(app opens) (You must include this API to enable
tracking)
[[AppsFlyerTracker sharedTracker] trackAppLaunch];
}
ThisAPIenablesAppsFlyertotrackpostinstallevents.Theseeventsaredefinedbytheadvertiserand
includeaneventnameinadditiontooptionaleventvalues.
Trackinginappeventshelpsyoumeasureandanalysehowloyalusersdiscoveryourapp,andattribute
themtospecificcampaigns/mediasources.Itisrecommendedtotakethetimeanddefinetheeventsyou
wouldliketomeasuretoallowyoutotrackROI(ReturnonInvestment)andLTV(LifetimeValue).
Syntax:
Countingrevenueaspartofarichinappevent:
Usetheaf_revenue(
AFEventParamRevenue
constant)eventparametertocountrevenueaspartofaninappevent.Youcanpopulateitwithany
numericvalue,positiveornegative.Notethataf_price(
AFEventParamPrice
)willnotbecountedas
revenueandisadescriptiveparameterwhichdoesnotaffectrevenueandLTVmeasurements.
Example1:
Levelachievedinappevent
Thiswillgenerateaneventoftypeaf_level_achievedwiththefollowingeventvalues:
{af_level:9,af_score:100}
support@appsflyer.com
www.appsflyer.com
Example2:
PurchaseEvent
Thiswillgenerateaneventoftypeaf_purchasewiththefollowingeventvalues:
{af_content_id:1234567,af_content_type:category_a,af_revenue:200,af_currency:USD}
Thepurchaseeventabovecontainsa$200revenuewhichwillappearasrevenueinthedashboard.
FormoreinformationseeAppendixA:AppsFlyerRichInAppEvents
6. Advanced Integration
TheAPIsbelowareoptionalandarepartoftheadvancedintegrationwithAppsFlyerSDK.
YoucansetaglobalcurrencycodeusingtheAPIbelow,inadditiontospecificcurrencycodesthat
canbeusedaspartofeachinappeventthatissenttoAppsFlyer.Theglobalcurrencycodewillbe
usedwhenaf_currency(
AFEventParamCurrency
)isnotsentaspartofaninappevent.
USDisthedefaultvalue.PleasefindacceptableISOcurrencycodes
here
UsethefollowingAPIinordertosetthecurrencycode:
AnAppsFlyerproprietaryuniqueIDiscreatedforeverynewinstallofanapp.AppsFlyersuniqueID
isthemainIDusedbyAppsFlyerintheReportsandAPIs.
UsethefollowingAPIInordertogetAppsFlyersuniqueID:
support@appsflyer.com
www.appsflyer.com
SettingyourowncustomerIDwillenableyoutocrossreferenceyourownuniqueIDwith
AppsFlyersuniqueIDandtheotherdevicesIDs.ThisIDwillbeavailableinAppsFlyerCSVreports
alongwithpostbacksAPIsforcrossreferencingwithyourinternalIDs.
TosetyourcustomeruserID:
ImportantNotes:
ItisrecommendedtosetyourcustomeruserIDassoonaspossibleasitwillonlybe
associatedtoeventsreportedaftersettingthisattribute.
YoumustsettheCustomerUserIDusingthisAPIinordertouseAppsFlyersintegrations
withAnalyticsplatformssuchasMixpanelandSwrve.
AppsFlyerallowsyoutoaccesstheuserattributiondatainrealtimedirectlyattheSDKlevel.It
enablesyoutocustomizethelandingpageauserseesontheveryfirstappopenafterafreshapp
install.
Formoreinformationregardingthisadvancedfunctionality,
readhere
.
AppsFlyerenablesyoutoreportoneormoreoftheusersemailaddresses.Thedevelopershould
collecttheemailaddressesfromtheuserandreportittoAppsFlyeraccordingtothedevelopers
desiredencryptionmethod.Thefollowingencryptionmethodsareavailable:Sha1,MD5andplain.
Example:
AppsFlyerenablesyoutoreportlaunchesinitiatedthroughdeeplinksandtoanalysethe
performanceofyourretargetingattributioncampaigns.
Toreportsuchlaunches,simplycallthe
handleOpenURL
methodfromtheappdelegates
openURL
method:
support@appsflyer.com
www.appsflyer.com
AppsFlyersSDKcanprovidein-apppurchaseserververification.Tosetreceiptvalidationtracking
youneedtocallthe
validateAndTrackInAppPurchase
methodinsidetheSKStoreKits
completeTransaction
:callback.Thiscallwillautomaticallygenerateanaf_purchasein-app
event.
[[AppsFlyerTracker sharedTracker]
validateAndTrackInAppPurchase:@"in-app-purchase-success"
eventNameIfFailed:@"in-app-purchase-failed"
withValue:@YOUR_VALUE
withProduct:@YOUR_PRODUCT_IDENTIFIER
price:@PRODUCT_PRICE
success:^(NSDictionary *result){ }
failure:^(NSError *error, id response) { }
}];
Thiscallhastwocallbackblocks,oneforsuccessandoneforfailure(foranyreason,including
validationfail).Onsuccess,adictionarywillbereturnedwiththereceiptvalidationdataprovidedby
Applesservers.
Important:Fortestingpurposes,werecommendtosetthe
useReceiptValidationSandbox
flagto
YES,asthiswillredirecttherequeststoApplesandboxservers.
Example:
- (void)completeTransaction:(SKPaymentTransaction*)transaction {
// getProductByIdFromCache is your implementation for caching
//your SKProduct items
SKProduct *product = [self getProductByIdFromCache:
transaction.payment.productIdentifier];
[[AppsFlyerTracker sharedTracker]
validateAndTrackInAppPurchase:@"in-app-purchase-success"
eventNameIfFailed:@"in-app-purchase-failed"
support@appsflyer.com
www.appsflyer.com
AppsFlyersSDKcommunicateswithitsserversoverHTTPS.Incaseyouchoosetodisablethis
(notrecommended)
,youcansettheisHTTPSpropertytoNO.ThedefaultisYES.
AppsFlyerprovidesyouamethodtoopt-outspecificusersfromAppsFlyeranalytics.Thismethod
complieswiththelatestprivacyrequirementsandcomplieswithFacebookdataandprivacypolicies.
DefaultisNO,meaningtrackingisenabledbydefault.PleaseusethisAPIduringtheSDK
initializationinSection4toexplicitlyoptout:
AppsFlyerSDKwillcollectIDFAonlyifAdSupport.frameworklibraryisincludedinyourproject.No
needtoexplicitlyopt-inoropt-out.However,incaseyouwouldliketoexplicitlyopt-outIDFAplease
usethefollowingAPIduringtheSDKinitializationinSection4:
support@appsflyer.com
www.appsflyer.com
AppsFlyersrichinappeventsprovideadvertiserswiththeabilitytotrackanypostinstalleventandattribute
ittoamediasourceandcampaign.
Aninappeventiscomprisedofaneventnameandeventparameters(seebelowlistsofrecommended
eventandparameternames)
Syntax:
eventName
isanystringtodefinetheeventname.
values
isadictionaryofeventparametersthatcomprisearichevent.
Example1:
af_add_to_cartofasingleitemwiththevalueof9.99USD,content_id234234andoftypecategory_a:
Thefollowingin
appeventtypesaredefinedandrecommended:
EventStringConstant
EventStringName
AFEventLevelAchieved
af_level_achieved
AFEventAddPaymentInfo
af_add_payment_info
AFEventAddToCart
af_add_to_cart
AFEventAddToWishlist
af_add_to_wishlist
AFEventCompleteRegistration
af_complete_registration
AFEventTutorialCompletion
af_tutorial_completion
AFEventInitiatedCheckout
af_initiated_checkout
AFEventPurchase
af_purchase
AFEventRate
af_rate
AFEventSearch
af_search
AFEventSpentCredits
af_spent_credits
AFEventAchievementUnlocked
af_achievement_unlocked
support@appsflyer.com
www.appsflyer.com
AFEventContentView
af_content_view
AFEventListView
af_list_view
AFEventTravelBooking
af_travel_booking
AFEventShare
af_share
AFEventInvite
af_invite
AFEventLogin
af_login
AFEventReEngage
af_re_engage
AFEventUpdate
af_update
AFEventOpenedFromPushNotification
af_opened_from_push_notification
Thefollowingsectiondescribestherecommendedstructureofeacheventtypetogetherwiththeparameters
mappingstoFacebook,TwitterandCriteo:
af_level_achieved
Description:Usedtotrackgamelevelevents.
Recommendedattributes:af_level,af_score
FacebookMappedEvent:fb_mobile_level_achieved
TwitterMappedEvent:LEVEL_ACHIEVED
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_level
fb_level
level
af_score
af_add_payment_info
Description:Usedtotrackpaymentinfoconfigurationstatus.
Recommendedattributes:af_success
FacebookMappedEvent:fb_mobile_add_payment_info
TwitterMappedEvent:ADDED_PAYMENT_INFO
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_success
fb_success
user_payment_info
support@appsflyer.com
www.appsflyer.com
10
af_add_to_cart
Description:Usedtotrackaddtocarteventsofspecificitems.
Recommendedattributes:af_price,af_content_type,af_content_id,af_currency,af_quantity
FacebookMappedEvent:fb_mobile_add_to_cart
TwitterMappedEvent:ADD_TO_CART
CriteoMappedEvent:viewBasket
AttributesMapping:
AppsFlyer
Criteo
af_price
_valueToSum
price_micro*
price**
af_content_type
fb_content_type
content_type
af_content_id
fb_content_id
content_id
item_id
af_currency
fb_currency
price_currency
af_quantity
number_items
quantity
af_add_to_wishlist
Description:Usedtotrackaddtowishlisteventsofspecificitems.
Recommendedattributes:af_price,af_content_type,af_content_id,af_currency,af_quantity
FacebookMappedEvent:fb_mobile_add_to_wishlist
TwitterMappedEvent:ADD_TO_WISHLIST
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_price
_valueToSum
price_micro*
af_content_type
fb_content_type
content_type
af_content_id
fb_content_id
content_id
af_currency
fb_currency
price_currency
af_quantity
number_items
af_complete_registration
support@appsflyer.com
www.appsflyer.com
11
Description:Usedtotrackuserregistrationmethods.
Recommendedattributes:af_registration_method
FacebookMappedEvent:fb_mobile_complete_registration
TwitterMappedEvent:SIGN_UP
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_registration_method
fb_registration_method
registration_method
af_tutorial_completion
Description:Usedtotracktutorialcompletions.
Recommendedattributes:af_success,af_content_id
FacebookMappedEvent:fb_mobile_tutorial_completion
TwitterMappedEvent:TUTORIAL_COMPLETE
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_success
fb_success
af_content_id
fb_content_id
content_id
af_initiated_checkout
Description:Usedtotrackcheckoutevents.
Recommendedattributes:af_price,af_content_type,af_content_id,af_quantity,af_payment_info_available,
af_currency
FacebookMappedEvent:fb_mobile_initiated_checkout
TwitterMappedEvent:CHECKOUT_INITIATED
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_price
_valueToSum
price_micro*
af_content_type
fb_content_type
content_type
af_content_id
fb_content_id
content_id
support@appsflyer.com
www.appsflyer.com
12
af_currency
fb_currency
price_currency
af_quantity
fb_num_items
number_items
af_payment_info_available
fb_payment_info_available
user_payment_info
af_purchase
Description:Usedtotrackpurchaseevents(andassociaterevenuetothem).
Recommendedattributes:af_revenue,af_content_type,af_content_id,af_quantity,af_currency
FacebookMappedEvent:fb_mobile_purchase
TwitterMappedEvent:PURCHASE
CriteoMappedEvent:trackTransaction
AttributesMapping:
AppsFlyer
Criteo
af_revenue*
_valueToSum
price_micro**
price***
af_content_type
fb_content_type
content_type
af_content_id
fb_content_id
content_id
item_id
af_currency
fb_currency
price_currency
af_quantity
fb_num_items
number_items
quantity
af_validated
af_receipt_id
*af_revenuewillbecountedasrevenueinAppsFlyersplatform
af_rate
Description:Usedtotrackapp/itemratingevents.
Recommendedattributes:af_rating_value,af_content_type,af_content_id,af_max_rating_value
FacebookMappedEvent:fb_mobile_rate
TwitterMappedEvent:RATED
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_rating_value
_valueToSum
price_micro
support@appsflyer.com
www.appsflyer.com
13
af_content_type
fb_content_type
content_type
af_content_id
fb_content_id
content_id
af_max_rating_value
fb_max_rating_value
max_rated_value
af_search
Description:Usedtotracksearchevents.
Recommendedattributes:af_content_type,af_search_string,af_success
FacebookMappedEvent:fb_mobile_search
TwitterMappedEvent:SEARCH
CriteoMappedEvent:viewSearch
AttributesMapping:
AppsFlyer
Criteo
af_content_type
fb_content_type
content_type
af_search_string
fb_search_string
search_string
af_date_a
din
af_date_b
dout
af_destination_a
af_destination_b
af_success
fb_success
af_spent_credits
Description:Usedtotrackcreditspendevents.
Recommendedattributes:af_price,af_content_type,af_content_id
FacebookMappedEvent:fb_mobile_spent_credits
TwitterMappedEvent:SPENT_CREDITS
CriteoMappedEvent:trackTransaction
AttributesMapping:
AppsFlyer
Criteo
af_price
_valueToSum
price_micro*
price**
af_content_type
fb_content_type
content_type
support@appsflyer.com
www.appsflyer.com
14
af_content_id
fb_content_id
content_id
item_id
af_achievement_unlocked
Description:Usedtotrackachievementunlockingevents.
Recommendedattributes:af_description
FacebookMappedEvent:fb_mobile_achievement_unlocked
TwitterMappedEvent:ACHIEVEMENT_UNLOCKED
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_description
fb_description
description
af_content_view
Description:Usedtotrackcontentviewevents.
Recommendedattributes:af_price,af_content_type,af_content_id,af_currency
FacebookMappedEvent:fb_mobile_content_view
TwitterMappedEvent:CONTENT_VIEW
CriteoMappedEvent:viewProduct/viewListing
AttributesMapping:
AppsFlyer
Criteo
af_price
_valueToSum
price_micro*
price
af_content_type
fb_content_type
content_type
af_content_id
fb_content_id
content_id
item_id
af_currency
fb_currency
price_currency
af_list_view
Description:Usedtotracklistingsviewevents.
Recommendedattributes:af_content_type,af_content_list
FacebookMappedEvent:
TwitterMappedEvent:
CriteoMappedEvent:viewListing
AttributesMapping:
support@appsflyer.com
www.appsflyer.com
15
AppsFlyer
Criteo
af_content_type
af_content_list
product
af_travel_booking
Description:Usedtotracktravelbookingevents(andassociaterevenuetothem).
Recommendedattributes:af_revenue,af_destination_a,af_destination_b,af_class,af_description,
af_customer_user_id,af_content_type,af_content_id,af_date_a,af_date_b
FacebookMappedEvent:fb_mobile_purchase
TwitterMappedEvent:PURCHASE
CriteoMappedEvent:trackTransaction
AttributesMapping:
AppsFlyer
Criteo
af_revenue*
_valueToSum
price_micro**
price***
af_customer_user_id
cid
af_content_type
fb_content_type
content_type
af_content_id
fb_content_id
content_id
af_class
af_date_a
din
af_date_b
dout
af_destination_a
af_destination_b
af_success
fb_success
*af_revenuewillbecountedasrevenueinAppsFlyersplatform
af_share
Description:Usedtotracksharingevents.
Recommendedattributes:af_description
FacebookMappedEvent:None
TwitterMappedEvent:SHARE
support@appsflyer.com
www.appsflyer.com
16
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_description
description
af_invite
Description:Usedtotrackinvite(social)events.
Recommendedattributes:None
FacebookMappedEvent:None
TwitterMappedEvent:INVITE
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_description
description
af_login
Description:Usedtotrackuserloginevents.
Recommendedattributes:None
FacebookMappedEvent:None
TwitterMappedEvent:LOGIN
CriteoMappedEvent:None
af_reengage
Description:Usedtotrackuserreengagementevents.
Recommendedattributes:None
FacebookMappedEvent:None
TwitterMappedEvent:RE_ENGAGE
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_description
description
af_opened_from_push_notification
support@appsflyer.com
www.appsflyer.com
17
Description:Usedtotrackappopensfrompushnotificationevents.
Recommendedattributes:None
FacebookMappedEvent:None
TwitterMappedEvent:None
CriteoMappedEvent:None
af_update
Description:Usedtotrackupdateevents.
Recommendedattributes:af_content_id
FacebookMappedEvent:None
TwitterMappedEvent:UPDATE
CriteoMappedEvent:None
AttributesMapping:
AppsFlyer
Criteo
af_content_id
content_id
OptionalParameters:
Inadditiontotherecommendedparametersthatcouldbepassedwitheachevent,theparametersbelow
aredefinedandcanbesentaspartoftheeventdictionaryvalue:
ParameterStringConstant
ParameterStringName
RecommendedValueType
AFEventParamRevenue
af_revenue*
Float
AFEventParamPrice
af_price
Float
AFEventParamLevel
af_level
Int
AFEventParamSuccess
af_success
Boolean
AFEventParamContentType
af_content_type
String
AFEventParamContentList
af_content_list
Arrayofstrings
AFEventParamContentId
af_content_id
String
AFEventParamCurrency
af_currency
String
AFEventParamRegistrationMethod
af_registration_method
String
AFEventParamQuantity
af_quantity
Int
AFEventParamPaymentInfoAvailable af_payment_info_available
Boolean
AFEventParamRatingValue
af_rating_value
Float
AFEventParamMaxRatingValue
af_max_rating_value
Float
AFEventParamSearchString
af_search_string
String
support@appsflyer.com
www.appsflyer.com
18
AFEventParamDescription
af_description
String
AFEventParamScore
af_score
Int
AFEventParamDestinationA
af_destination_a
String
AFEventParamDestinationB
af_destination_b
String
AFEventParamClass
af_class
String
AFEventParamDateA
af_date_a
String
AFEventParamDateB
af_date_b
String
AFEventParamEventStart
af_event_start
Unixtime
AFEventParamEventEnd
af_event_end
Unixtime
AFEventParamLat
af_lat
Int
AFEventParamLong
af_long
Int
AFEventParamCustomerUserId
af_customer_user_id
String
AFEventParamValidated
af_validated
String
AFEventParamReceiptId
af_receipt_id
String
AFEventParam1
af_param_1
String
AFEventParam2
af_param_2
String
AFEventParam3
af_param_3
String
AFEventParam4
af_param_4
String
AFEventParam5
af_param_5
String
AFEventParam6
af_param_6
String
AFEventParam7
af_param_7
String
AFEventParam8
af_param_8
String
AFEventParam9
af_param_9
String
AFEventParam10
af_param_10
String
*af_revenueistheonlyparameterthatisusedforrevenuecalculations.Useitforeventsthatactually
representrevenuegenerationinyourbusinesslogic.Youcanuseaf_priceasamonetaryparameterthatwill
notbecountedasrevenue(suchasinanAddtoCartevent).
support@appsflyer.com
www.appsflyer.com