When you run mobile campaigns, boost of new app installs are often one of the main goals. Our easy to install Tracking SDK will enable campaign app installs tracking and reporting in Adform platform without need to deal with 3rd party SDKs and invest tons of time into that.
If you have any issues or suggestions please contact [email protected]
Apple introduced a new AppTrackingTransparency framework and tracking permission in iOS 14. To support these changes you will need to make couple of small changes in Adform Tracking SDK integration. For more information check Migration Guide down bellow.
The use of Adform Tracking SDK requires the following:
- Xcode 13.0 or later.
- Requires deployment target 9.0 or later.
- Requires ARC to be enabled.
Please folow Migration guide below if you are updating SDK to version 1.0.
Tracking SDK is also available on these platforms:
The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.
You can add Adform Tracking SDK as a dependency to your project through Xcode UI or add it to your project's Package.swift
file like this:
dependencies: [
.package(url: "https://github.com/adform/adform-tracking-ios-sdk", .upToNextMajor(from: "1.7.4"))
]
Important! Xcode 12 has a bug where static frameworks distributed through SPM sometimes get embedded incorrectly into the app. This issue is mentioned in Xcode 12.4 release notes. If the validation of your archived app fails you may need to use a workaround that strips the embedded frameworks after the build. You can use this build phase script to remove embedded frameworks from the app:
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
rm -rf "${APP_PATH}/Frameworks/AdformTracking.framework"
rm -rf "${APP_PATH}/Frameworks/ProtocolBuffers.framework"
rm -rf "${APP_PATH}/Plugins/AdformTracking.framework"
rm -rf "${APP_PATH}/Plugins/ProtocolBuffers.framework"
Adform Tracking SDK is available via CocoaPods. To integrate SDK using CocoaPods, you need to edit Podfile
and specify the AdformTracking
pod.
pod 'AdformTracking', '~> 1.7.4'
For more information about CocoaPods visit CocoaPods site.
Adform Tracking SDK is available via Carthage.
- To integrate SDK using Carthage, you need to specify it in
Cartfile
.
binary "https://raw.githubusercontent.com/adform/adform-tracking-ios-sdk/master/AdformTracking.json"
- Adform Tracking SDK uses Protocol Buffers - Google's data interchange format. Therefore you need to import Protobuf library to your project too.
binary "https://raw.githubusercontent.com/adform/protobuf-ios/master/ProtocolBuffers.json"
- Our SDK and Protocol Buffers library are distributed as static frameworks. Therefore, you should not add them to input/output files in Carthage copy-frameworks Build Phase.
For more information about Carthage visit Carthage site.
- Download latest build version of Adform Tracking SDK.
- Drag AdformTracking.framework to your project.
- When asked select Copy items into destination group's folder.
-
Then select AdformTracking.xcframework in project navigator, go to file inspector and add it to your applications target (Target Membership).
-
Adform Tracking SDK uses Protocol Buffers - Google's data interchange format. Therefore you need to import Protobuf library to your project. You can use it either directly from Google source code or integrate our framework build.
-
If you get a
missing symbols error
, it may mean that automatic framework linking has failed, in this case try to addAdSupprt.framework
dependency explicitly in you project. -
If you get a
bundle format unrecognized, invalid, or unsuitable
error while integrating the SDK, it probably means one of two problems:- That you are integrating SDK with Carthge and have added AdformTracking.framework and ProtocolBuffers.framework to input/output files in Carthage copy-frameworks Build Phase. You should not add these frameworks to copy-frameworks Build Phase.
- You have selected
Embed
in Framework and Libraries project configuration. This configuration should be selected toDo Not Embed
.
-
Import
AdformTracking
inAppDelegate.h
-
In
application:didFinishLaunchingWithOptions:
method callstartTracking:waitForPermissions:
method with your Client Tracking ID andwaitForPermissions
true
. This method should be called only one time, when app starts.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
AdformTrackingSDK.sharedInstance().startTracking(yourTrackingId, waitForPermissions: true)
return true
}
Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:true];
return YES;
}
- Then call
requestTrackingPermissions
to get user permission to use Advertising Identifier for tracking. Calling this method will present systemic permission alert. Therefore, it is up to you to decide when it is best to show this alert.
Important iOS 15 support
On iOS 15 you must make sure that tracking permissions are requested when app is in active state. Otherwise, permission request will not be presented.
if #available(iOS 14.0, *) {
AdformTrackingSDK.sharedInstance().requestTrackingPermissions()
}
Objective-C
if (@available(iOS 14.0, *)) {
[[AdformTrackingSDK sharedInstance] requestTrackingPermissions];
}
- Add
NSUserTrackingUsageDescription
entry to your appsInfo.plist
file.
Thats it! You are ready to go. Now in Adform system will see default tracking points (Download, Start, Update), when they are triggered.
- Optionally, if you don't want to use Advertising Identifier for tracking, you may not ask user for permissions. In this case you must pass
false
towaitForPermissions
when callingstartTracking:waitForPermissions:
.
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
AdformTrackingSDK.sharedInstance().startTracking(yourTrackingId, waitForPermissions: false)
return true
}
Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:false];
return YES;
}
- Optionally you can set custom application name and custom variables before calling
startTracking:
.
AdformTrackingSDK.sharedInstance().setAppName("CustomApplicationName")
let order = AFOrder()
order.firstName = "Fist name"
order.lastName = "Last name"
// You also can set other custom variables.
order.setCustomVariable("var1", forKey: 1)
order.setSystemVariable("sysVar1", forKey: 1)
order.setNumericSystemVariable(123.45, forKey: 1)
AdformTrackingSDK.sharedInstance().setOrder(order)
AdformTrackingSDK.sharedInstance().startTracking(yourTrackingId, waitForPermissions: true)
Objective-C
[[AdformTrackingSDK sharedInstance] setAppName:@"CustomApplicationName"];
AFOrder *order = [AFOrder new];
order.firstName = @"First Name";
order.lastName = @"Last Name";
// You also can set other custom variables.
[order setCustomVariable:@"var1" forKey:1];
[order setSystemVariable:@"sysVar1" forKey:1];
[order setNumericSystemVariable:@(123.45) forKey:1];
[[AdformTrackingSDK sharedInstance] setOrder:order];
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:false];
-
For sending custom tracking events manually you need to import
AdformTracking
in any class you want to send events from, in provided example we useViewController.h
. -
Create an
AFTrackPoint
instance with your clientTracking_ID
. After that you can set tracking point name, custom variables and finally send the tracking point. -
When defining variables' it's required to keep in mind, that there are different type of variables:
- Custom variables with predefined names (orderid, currency, firstname, etc.)
- Custom variables (var1-var10)
- System variables (sv1-sv89)
- Numeric system variables (svn1, svn2)
-
Create a
AFTrackPoint
instance with your track point id, set custom application name, custom parameters, a.k.a. order, and send the track point.
let trackPoint = AFTrackPoint(trackPoint: yourTrackingId)
trackPoint.setSectionName("Custom Tracking Point Name")
let order = AFOrder()
order.orderId = "Order ID"
order.sale = 1234
order.currency = "Eur"
order.orderStatus = "Sold"
order.firstName = "First Name"
order.lastName = "Last Name"
order.country = "Country"
order.address1 = "Address 1"
order.address2 = "Address 2"
order.zip = "ZIP code"
order.email = "E-mail"
order.phone = "Phone"
order.gender = "Gender"
order.ageGroup = "Age group"
order.basketSize = 12
// You also can set other custom variables.
order.setCustomVariable("var1", forKey: 1) // key defines variable index, e.g. forKey:3 means Var3
order.setSystemVariable("sysVar1", forKey: 1) // key defines variable index, e.g. forKey:3 means Sv3
order.setNumericSystemVariable(123.45, forKey: 1) // key defines variable index, e.g. forKey:2 means Svn2; Only numeric values allowed
trackPoint.setOrder(order)
AdformTrackingSDK.sharedInstance().send(trackPoint)
Objective-C
AFTrackPoint *trackPoint = [[AFTrackPoint alloc] initTrackPoint:yourTrackingId];
[trackPoint setSectionName:@"CCustom Tracking Point Name"];
AFOrder *order = [AFOrder new];
order.orderId = @"Order ID";
order.sale = 1234; //numeric format
order.currency = @"Eur";
order.orderStatus = @"Sold";
order.firstName = @"First Name";
order.lastName = @"Last Name";
order.country = @"Country";
order.address1 = @"Address 1";
order.address2 = @"Address 2";
order.zip = @"ZIP code";
order.email = @"E-mail";
order.phone = @"Phone";
order.gender = @"Gender";
order.ageGroup = @"Age group";
order.basketSize = 12; //numeric format
// You can also set other custom variables.
[order setCustomVariable:@"Var1 value" forKey:1]; // forKey defines variable index, e.g. forKey:3 means Var3
[order setSystemVariable:@"Sv1 value" forKey:1]; // forKey defines variable index, e.g. forKey:3 means Sv3
[order setNumericSystemVariable:@(123.45) forKey:1]; // forKey defines variable index, e.g. forKey:2 means Svn2; Only numeric values allowed
[trackPoint setOrder:order];
[[AdformTrackingSDK sharedInstance] sendTrackPoint:trackPoint];
To logicaly group tracking points you can set separate app names for each custom tracking point. This would allow to use app name together with custom section name.
let trackPoint = AFTrackPoint(trackPoint: yourTrackingId)
trackPoint.setSectionName("Custom Tracking Point Name")
trackPoint.setAppName("Custom_app_name-Section_name")
AdformTrackingSDK.sharedInstance().send(trackPoint)
Objective-C
AFTrackPoint *trackPoint = [[AFTrackPoint alloc] initTrackPoint:yourTrackingId];
[trackPoint setSectionName:@"Custom Tracking Point Name"];
[trackPoint setAppName:@"Custom_app_name-Section_name"];
[[AdformTrackingSDK sharedInstance] sendTrackPoint:trackPoint];
Also it is posible to send additional product variables information with tracking points. To do so you have two options, first use addProduct:
method and add products to the trackpoint one at a time, second use setProducts:
method and set an array of products. Either way you must set AFProduct
objects.
let trackPoint = AFTrackPoint(trackPoint: yourTrackingId)
trackPoint.setSectionName("Custom Application Name")
let product = AFProduct(
categoryName: "Product category name",
categoryId: "Product category id",
productName: "Product name",
productId: "Product id",
weight: 10,
step: 1,
productSales: 12.58,
productCount: 2,
custom: "Custom product information"
)
trackPoint.addProduct(product)
AdformTrackingSDK.sharedInstance().send(trackPoint)
Objective-C
AFTrackPoint *trackPoint = [[AFTrackPoint alloc] initTrackPoint:yourTrackingId];
[trackPoint setSectionName:@"Custom Tracking Point Name"];
AFProduct *product = [[AFProduct alloc] initWithCategoryName:@"Product category name"
categoryId:@"Product category id"
productName:@"Product name"
productId:@"Product id"
weight:10
step:1
productSales:12.58
productCount:2
custom:@"Custom product information"];
[trackPoint addProduct:product];
[[AdformTrackingSDK sharedInstance] sendTrackPoint:trackPoint];
Also for same tracking point you can list more than one product variables list:
let trackPoint = AFTrackPoint(trackPoint: yourTrackingId)
trackPoint.setSectionName("Custom Application Name")
let product1 = AFProduct(
categoryName: "Product category name",
categoryId: "Product category id",
productName: "Product name",
productId: "Product id",
weight: 10,
step: 1,
productSales: 12.58,
productCount: 2,
custom: "Custom product information"
)
let product2 = AFProduct(
categoryName: "Product category name",
categoryId: "Product category id",
productName: "Product name",
productId: "Product id",
weight: 10,
step: 1,
productSales: 12.58,
productCount: 2,
custom: "Custom product information"
)
trackPoint.setProducts([product1, product2])
AdformTrackingSDK.sharedInstance().send(trackPoint)
Objective-C
AFTrackPoint *trackPoint = [[AFTrackPoint alloc] initTrackPoint:yourTrackingId];
[trackPoint setSectionName:@"Custom Tracking Point Name"];
AFProduct *product1 = [[AFProduct alloc] initWithCategoryName:@"Product category name"
categoryId:@"Product category id"
productName:@"Product name"
productId:@"Product id"
weight:10
step:1
productSales:12.58
productCount:2
custom:@"Custom product information"];
AFProduct *product2 = [[AFProduct alloc] initWithCategoryName:@"Product category name"
categoryId:@"Product category id"
productName:@"Product name"
productId:@"Product id"
weight:10
step:1
productSales:12.58
productCount:2
custom:@"Custom product information"];
[trackPoint setProducts:@[product1, product2]];
[[AdformTrackingSDK sharedInstance] sendTrackPoint:trackPoint];
If you want to send only part of available product data, you can avoid using big init method by setting those properties manually after creating an object with default initializer.
let trackPoint = AFTrackPoint(trackPoint: yourTrackingId)
let product = AFProduct()
product.productName = "My Product Name"
trackPoint.addProduct(product)
AdformTrackingSDK.sharedInstance().send(trackPoint)
Objective-C
AFTrackPoint *trackPoint = [[AFTrackPoint alloc] initTrackPoint:Tracking_ID];
AFProduct *product = [AFProduct new];
product.productName = @"My Product Name";
[trackPoint addProduct:product];
[[AdformTrackingSDK sharedInstance] sendTrackPoint:trackPoint];
It is possible to send tracking information to multiple clients by defining each client's Tracking id.
In order to start tracking, please use an example below:
AdformTrackingSDK.sharedInstance()
.startTracking(
withIds: [yourTrackingId1, yourTrackingId2, yourTrackingId3],
waitForPermissions: true
)
Objective-C
[[AdformTrackingSDK sharedInstance] startTrackingWithIds:@[yourTrackingId1, yourTrackingId2, yourTrackingId3] waitForPermissions:true];
To send custom tracking points for multiple clients, you should use AFTrackPointsBuilder
class. It helps you create multiple trackpoints with same information, but differrent tracking id.Example bellow ilustrates how to do so:
let trackPointBuilder = AFTrackPointsBuilder()
// You must set at least these properties:
trackPointBuilder.trackPointIds = [yourTrackingId1, yourTrackingId2, yourTrackingId3]
trackPointBuilder.sectionName = "Custom trackpoint"
// Additionally you can set more information to track.
trackPointBuilder.applicationName = "Custom application name"
trackPointBuilder.order = yourOrder;
// Create trackpoints
let trackingPoints = trackPointBuilder.build()
// Send trackpoints.
AdformTrackingSDK.sharedInstance().send(trackingPoints)
Objective-C
AFTrackPointsBuilder *trackPointBuilder = [[AFTrackPointsBuilder alloc] init];
// You must set at least these properties:
trackPointBuilder.trackPointIds = @[yourTrackingId1, yourTrackingId2, yourTrackingId3];
trackPointBuilder.sectionName = @"Custom trackpoint";
// Additionally you can set more information to track.
trackPointBuilder.applicationName = @"Custom application name";
trackPointBuilder.order = yourOrder;
// Create trackpoints
NSArray *trackPoints = [trackPointBuilder build];
// Send trackpoints.
[[AdformTrackingSDK sharedInstance] sendTrackPoints:trackPoints];
You can disable the Adform Tracking SDK from tracking any events by calling setEnabled:
with parameter NO
. This setting is remembered between application launches. By default tracking is enabled.
AdformTrackingSDK.sharedInstance().setEnabled(false)
Objective-C
[[AdformTrackingSDK sharedInstance] setEnabled:NO];
You can check if tracking is enabled by calling isEnabled
method.
Adform Tracking SDK uses deep-link tracking to attribute part of Facebook events. You should implement it if you are going to use our SDK for Facebook tracking.
The implementation is very simple, you just have to call AdformTrackingSDK
method applicationOpenUrl:sourceApplication:
in your AppDelegate
class's method application:openURL:sourceApplication:annotation:
and pass url and sourceApplication parameters.
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return AdformTrackingSDK.sharedInstance().applicationOpen(url, options: options)
}
Objective-C
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
return [[AdformTrackingSDK sharedInstance] applicationOpenURL:url options:options];
}
Adform Tracking SDK allows you to track user device SIM card state. This feature allows you to see if a user device has a SIM card inserted into it.
This feature is turned off by default, therefore if you want to use it, you need to enable it. To do so you just need to use the setSendSimCardStateEnabled:
method.
AdformTrackingSDK.sharedInstance().setSendSimCardStateEnabled(true)
AdformTrackingSDK.sharedInstance().startTracking(yourTrackingId, waitForPermissions: true)
Objective-C
[[AdformTrackingSDK sharedInstance] setSendSimCardStateEnabled:true];
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:true];
By default AdformTracking sdk uses HTTPS protocol for network comunnications, but there is a possibility to disable it and use an insecure HTTP protocol. Example below shows you how to do it.
AdformTrackingSDK.sharedInstance().setHTTPSEnabled(false)
Objective-C
AdformTrackingSDK sharedInstance] setHTTPSEnabled:false];
By default Adform Tracking SDK will check CMP settings and use that information. More information about this here
It is possible to set GDPR and GDPR consent manually. You need to use setGdpr:
and setGDPRConsent:
methods. For GDPR consent you need to set base64-encoded string.
Example:
AdformTrackingSDK.sharedInstance().setGDPR(true)
let encodedGDPRConsent = "GgdprConsent".data(using: .utf8)?.base64EncodedString()
AdformTrackingSDK.sharedInstance().setGDPRConsent(encodedGDPRConsent)
Objective-C
[[AdformTrackingSDK sharedInstance] setGDPR:@(true)];
NSString *encodedGDPRConsent = [[@"GgdprConsent" dataUsingEncoding:NSUTF8StringEncoding] base64EncodedStringWithOptions:0];
[[AdformTrackingSDK sharedInstance] setGDPRConsent:encodedGDPRConsent];
By default Adform Tracking SDK will check CMP settings to get US Privacy value. More information about this can be found here:
It is also possible to set US Privacy value manually. You can do this using setUSPrivacy:
method.
Example:
let usPrivacy = "US_PRIVACY"
AdformTrackingSDK.sharedInstance().setUSPrivacy(usPrivacy)
Objective-C
NSString *usPrivacy = @"US_PRIVACY";
[[AdformTrackingSDK sharedInstance] setUSPrivacy:usPrivacy];
Adform Tracking SDK uses web view user-agent as one of the parameters to identify users and perform attribution. In some cases an issue may arise if you are firing some tracking points in your own web view, e.g. you are developing a hibrid application. In these cases attribution may not work because user-agent of your own web view and default web view user-agent used by our SDK may not match. To solve this issue Adform Tracking SDK provides a method to set a custom user agent.
Example:
AdformTrackingSDK.sharedInstance().setCustomUserAgent("YOUR CUSTOM USER AGENT")
Objective-C
[[AdformTrackingSDK sharedInstance] setCustomUserAgent:@"YOUR CUSTOM USER AGENT"];
You can enable debug mode by providing AFTDebugModeEnabled
launch argument. When debug mode is enabled SDK will print additional logs to the console. This may be usefull during development while integrating Adform Tracking SDK into your application.
In SDK version 1.0 was added functionality, which requires additional changes during update from older versions:
- If you are integrating SDK manually you need to add additional
SafariServices
framework dependency to your project. - Also if you are integrating SDK manually you need to import Google Protobuf library to your project. Instructions on how to do it can be found here.
TrackPoint
class have been renamed toAFTrackPoint
.getParameters
,addParameter:withValue:
andsetParameters:
methods ofAFTrackPoint
andAdformAdvertisingSDK
classes have been deprecated. Instead of them to set custom variables to tracking points you should usesetOrder:
method andAFOrder
class.
SafariServices
framework dependency is no longer needed by the SDK.
In iOS 14 we need to ask user for permission to use Advertising Identifier for tracking purposes. To do so, you will need to make these changes to SDK integration:
- Pass in
true
aswaitForPermissions
parameter tostartTracking
method.
AdformTrackingSDK.sharedInstance().startTracking(withIds: yourTrackingId, waitForPermissions: true)
Objective-C
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:true];
- Ask user for permission to access Advertising Identifier using
requestTrackingPermissions
method. Calling this method will present a systemic permissions alert, therefore it's up to you to decide when it is most apropriate to show it.
if #available(iOS 14.0, *) {
AdformTrackingSDK.sharedInstance().requestTrackingPermissions()
}
Objective-C
if (@available(iOS 14.0, *)) {
[[AdformTrackingSDK sharedInstance] requestTrackingPermissions];
}
- Add
NSUserTrackingUsageDescription
entry to your appsInfo.plist
file.
- iOS 16 support.
- iOS 15 support.
- Adds debug mode, that can be enabled with
AFTDebugModeEnabled
launch argument. When debug mode is enabled SDK will print additional debug logs into the console.
- Fix Swift Package Manager dependencies
- Add Swift Package Manager support.
- Change framework format to .xcframework.
- No carthage support for this version. Carthage doesn't support .xcframework type yet. Use 1.7.0 version if you need carthage support.
- Add iOS 14, AppTrackingTransparency support.
- No cocoapods support for this version. Cocoapods require .xcframework type to work with iOS 14, therefore use 1.7.1 version.
- IAB CCPA Compliance Framework support.
- Update Framework structure.
- Fix web view multithreading issue.
- Migrate UIWebView usage to WKWebView.
- IAB Transparent Consent Framework 2.0 support.
- Ad support for Carthage.
- Added ability to set custom user-agent.
- Fixed database initialization error issues that affected some users;
- Added GDPR support. More info in GDPR section.
- Removed usage of SFSafariViewController.
- Now SDK uses newest version of Protobuf library.
- Fixed issue when UIWebView was called from background thread;
- Fixed a typo;
- iOS 10 support;
- Now SDK uses Protocol Buffers v3.0.0-beta-3.1 library;
- Add basket size parameter to order;
- Improved app installs attribution;
- Multiple trackpoint support;
- Minor bug fixes;