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:
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.
Cartfile
.binary "https://raw.githubusercontent.com/adform/adform-tracking-ios-sdk/master/AdformTracking.json"
binary "https://raw.githubusercontent.com/adform/protobuf-ios/master/ProtocolBuffers.json"
For more information about Carthage visit Carthage site.
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 add AdSupprt.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:
Embed
in Framework and Libraries project configuration. This configuration should be selected to Do Not Embed
.Import AdformTracking
in AppDelegate.h
In application:didFinishLaunchingWithOptions:
method call startTracking:waitForPermissions:
method with your Client Tracking ID and waitForPermissions
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
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:true];
return YES;
}
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()
}
if (@available(iOS 14.0, *)) {
[[AdformTrackingSDK sharedInstance] requestTrackingPermissions];
}
NSUserTrackingUsageDescription
entry to your apps Info.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.
false
to waitForPermissions
when calling startTracking:waitForPermissions:
.func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
AdformTrackingSDK.sharedInstance().startTracking(yourTrackingId, waitForPermissions: false)
return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:false];
return YES;
}
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)
[[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 use ViewController.h
.
Create an AFTrackPoint
instance with your client Tracking_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:
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)
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)
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)
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)
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)
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
)
[[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)
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)
[[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)
}
- (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)
[[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)
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)
[[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)
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")
[[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:
SafariServices
framework dependency to your project.TrackPoint
class have been renamed to AFTrackPoint
.getParameters
, addParameter:withValue:
and setParameters:
methods of AFTrackPoint
and AdformAdvertisingSDK
classes have been deprecated. Instead of them to set custom variables to tracking points you should use setOrder:
method and AFOrder
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:
true
as waitForPermissions
parameter to startTracking
method.AdformTrackingSDK.sharedInstance().startTracking(withIds: yourTrackingId, waitForPermissions: true)
[[AdformTrackingSDK sharedInstance] startTracking:yourTrackingId waitForPermissions:true];
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()
}
if (@available(iOS 14.0, *)) {
[[AdformTrackingSDK sharedInstance] requestTrackingPermissions];
}
NSUserTrackingUsageDescription
entry to your apps Info.plist
file.AFTDebugModeEnabled
launch argument. When debug mode is enabled SDK will print additional debug logs into the console.link |
Stars: 4 |
Last commit: 1 year ago |
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics