iOS SDK

The Velocidi iOS SDK is open-source and can be found at github.com/velocidi/velocidi-ios-objc-sdk.

Installation

Installation with CocoaPods

To integrate VelocidiSDK into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '12.1'

project 'MyProject.xcodeproj'

target "MyProject" do

pod 'VelocidiSDK', '~> 0.3.2'

end

Then, run:

$ pod install

Installation with Carthage

To integrate VelocidiSDK into your Xcode project using Carthage, specify it in your Cartfile:

github "velocidi/velocidi-ios-objc-sdk" ~> 0.3.2

Then, run carthage to build the framework and drag the built VelocidiSDK.framework into your Xcode project.

Requirements

VelocidiSDK should work with any version of iOS equal or bigger than 11.0.

Setting up the SDK

Initialize the VelocidiSDK with the necessary trackingBaseUrl and the matchBaseUrl URLs. Without this, VelocidiSDK will not work. We suggest doing this when the application launches.

Swift

import VelocidiSDK

@UIApplicationMain

class AppDelegate: UIResponder, UIApplicationDelegate {

var window: UIWindow?

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

// Override point for customization after application launch.

let config = VSDKConfig(trackingBaseUrl: "https://tr.yourdomain.com", "https://match.yourdomain.com")!

VSDKVelocidi.start(config)

return true

}

Objective-C

@import VelocidiSDK;

@interface AppDelegate ()

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

// Override point for customization after application launch.

VSDKConfig * config = [[VSDKConfig alloc] initWithTrackingBaseUrl:@"https://tr.yourdomain.com": @"https://match.yourdomain.com"];

[VSDKVelocidi start: config];

return YES;

}

iOS 14 IDFA access

In iOS 14 Apple introduces changes to the way the Advertising Identifier (IDFA) can be accessed. In particular, developers are forced to ask the user permission to access the IDFA:

• https://developer.apple.com/app-store/user-privacy-and-data-use/
• https://developer.apple.com/documentation/apptrackingtransparency?language=objc

The Examples folder contains two example applications ready for iOS 14, which ask for user permission before using the IDFA to execute any requests.

The Velocidi iOS SDK itself will not execute any request if the user did not allow tracking to proceed.

Send a track event

A tracking event will log a user action in Velocidi's CDP.

In order to send a tracking event, create an instance of VSDKTrackingEvent. Then, call the singleton instance of VSDKVelocidi and use the track method.

Swift

import VelocidiSDK

...

let trackingEvent = VSDKPageView()

trackingEvent.siteId = "RandomSiteId"

trackingEvent.clientId = "RandomClientId"

VSDKVelocidi.sharedInstance().track(trackingEvent)

Objective-C

@import VelocidiSDK;

...

VSDKTrackingEvent * trackingEvent = [[VSDKPageView alloc] init];

trackingEvent.clientId = @"RandomSiteId";

trackingEvent.siteId = @"RandomClientId";

[VSDKVelocidi.sharedInstance track: trackingEvent]

You can also pass callback blocks that will be called when the request either succeeds or fails.

Swift

VSDKVelocidi.sharedInstance().track(trackingEvent, onSuccess:{ (response: URLResponse, responseObject: Any) in

print("Success! Response: \(response)")

}, onFailure:{(error: Error) in

print("Failed! Error: \(error.localizedDescription)")

})

Objective-C

[VSDKVelocidi.sharedInstance track: trackingEvent onSuccess: ^(NSURLResponse * response, id responseObject){

NSLog(@"Success! Response: %@", trackingNumber);

} onFailure: ^(NSError * error){

NSLog(@"Failed! Error: %@", [error localizedDescription]);

}];

There is a big list of tracking event classes to choose from. If none of them fits the desired action, you can also create your own custom tracking event

Make a match

Match requests are used to link multiple identifiers in Velocidi's CDP. This way, any action made with any of the identifiers, across multiple channels (Browser, Mobile App, ...), can be associated to the same user.

In VelocidiSDK, a match request will link the user's Advertising Identifier with other provided identifiers (like an internal ID). A typical use case for this is, for instance, during the login action, to associate the user's ID with Apple's Advertising Identifier (identifier used in all the tracking event requests).

Swift

@IBAction func sendMatchEvent(_ sender: Any) {

let userId1 = VSDKUserId(userId: "bar", "fooType")

let userId2 = VSDKUserId(userId: "baz", "fooType")

let idsArray = NSMutableArray(array: [userId1, userId2])

VSDKVelocidi.sharedInstance().match("1234-providerId-56789", userIds: idsArray, onSuccess:{ (response: URLResponse, responseObject: Any) in

print("Success! Response: \(response)")

}, onFailure:{(error: Error) in

print("Failed! Error: \(error.localizedDescription)")

})

}

Objective-C

- (IBAction)sendMatch:(id)sender {

VSDKUserId * userId1 = [[VSDKUserId alloc] initUserId:@"bar":@"fooType"];

VSDKUserId * userId2 = [[VSDKUserId alloc] initUserId:@"baz":@"fooType"];

NSMutableArray * idsArray = [[NSMutableArray alloc] initWithObjects: userId1, userId2, nil];

[VSDKVelocidi.sharedInstance match: @"1234-providerId-56789"

userIds: idsArray

onSuccess: ^(NSURLResponse * response, id responseObject){

NSLog(@"Success! Response: %@", trackingNumber);

} onFailure: ^(NSError * error){

NSLog(@"Failed! Error: %@", [error localizedDescription]);

}];

Available tracking events model classes

• VSDKAddToCart
• VSDKAppView
• VSDKOrderPlace
• VSDKPageView
• VSDKProductClick
• VSDKProductCustomization
• VSDKProductFeedback
• VSDKProductImpression
• VSDKProductView
• VSDKProductViewDetails
• VSDKRemoveFromCart
• VSDKSearch

Create your custom tracking event

If none of the available tracking events matches your needs you can also extend VSDKTrackingEvent and create your own.

Beware! Custom tracking events might not be interpreted by our services and will have limited functionality (logging and basic statistics). Please try to use one of the existing tracking events model classes or at least inherit from one of those classes when creating a custom event to ensure you make the most out of Velocidi's CDP.

Objective-C

Create a new Cocoa Touch class that inherits from VSDKTrackingEvent (or any of the other tracking event model classes).

Example:

CustomEvent.h

#import <VelocidiSDK/VelocidiSDK.h>

@interface CustomEvent : VSDKTrackingEvent

@property (nonnull) NSString *customType;

// Place below the desired fields you want to add to the tracking event

@property (nullable) NSString *customField;

@end

CustomEvent.m

#import "CustomEvent.h"

@implementation CustomEvent

- (instancetype) init {

if(self = [super init]){

// Only necessary when inheriting directly from VSDKTrackingEvent

self.type = @"custom"; //Don't change

// Only necessary when inheriting directly from VSDKTrackingEvent

self.customType = @"customEvent"; // Change to match the desired type of the custom event

}

return self;

}

@end

This new class can then be imported and used like any other tracking event:

#import "CustomEvent.h";

...

CustomEvent * trackingEvent = [[CustomEvent alloc] init];

trackingEvent.clientId = @"RandomSiteId";

trackingEvent.siteId = @"RandomClientId";

trackingEvent.customField = @"RandomCustomField";

[VSDKVelocidi.sharedInstance track: trackingEvent]

Swift

Due to limitations of the framework we use to serialize classes to JSON (JSONModel), a Swift class that inherits from VSDKTrackingEvent or any tracking event model class won't have its properties serialized when sending the event. To have this functionality you will have to create your custom event in Objective-C and import it into Swift:

1. Create a new Cocoa Touch class.
2. When prompted with the desired language, make sure to choose Objective-C. Press Next.

1. After creating the class you'll be asked if you want to configure an Objective-C bridging header. Press Create Bridging Header.

4. Three new files should have been created.

5. Import the created custom event class in the bridging header file (AppName-Bridging-Header.h):

//

// Use this file to import your target's public headers that you would like to expose to Swift.

//

#import "CustomEvent.h"

6. Add the desired fields to the custom event (see Objective-C instructions for custom events)

7. Use the newly created class as any other tracking event model class:

let trackingEvent = CustomEvent()

trackingEvent.siteId = "RandomSiteId"

trackingEvent.clientId = "RandomClientId"

trackingEvent.customField = "RandomCustomField"

If you had any problem with importing the Objective-C class into Swift, please take a look at Apple's guide on Importing Objective-C into Swift.