{"id":20936204,"url":"https://github.com/adzerk/audience-ios-objc-sdk","last_synced_at":"2025-12-12T06:18:07.254Z","repository":{"id":52175092,"uuid":"177781474","full_name":"adzerk/audience-ios-objc-sdk","owner":"adzerk","description":"Kevel Audience Objective-C SDK (VelocidiSDK) to integrate with iOS apps.","archived":false,"fork":false,"pushed_at":"2024-05-20T08:44:46.000Z","size":1423,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-02-28T12:36:58.820Z","etag":null,"topics":["audience"],"latest_commit_sha":null,"homepage":"https://docs.audience.kevel.com/sdk/ios","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adzerk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2019-03-26T12:11:49.000Z","updated_at":"2024-05-20T08:44:50.000Z","dependencies_parsed_at":"2022-08-24T00:30:50.987Z","dependency_job_id":null,"html_url":"https://github.com/adzerk/audience-ios-objc-sdk","commit_stats":null,"previous_names":["velocidi/velocidi-ios-objc-sdk"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzerk%2Faudience-ios-objc-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzerk%2Faudience-ios-objc-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzerk%2Faudience-ios-objc-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzerk%2Faudience-ios-objc-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adzerk","download_url":"https://codeload.github.com/adzerk/audience-ios-objc-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244870473,"owners_count":20523870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audience"],"created_at":"2024-11-18T22:18:21.706Z","updated_at":"2025-12-12T06:18:02.204Z","avatar_url":"https://github.com/adzerk.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Velocidi iOS SDK in Objective-C\n![Cocoapods platforms](https://img.shields.io/cocoapods/p/VelocidiSDK.svg)\n![Cocoapods](https://img.shields.io/cocoapods/v/VelocidiSDK.svg)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n\nVelocidiSDK is Kevel Audience Objective-C SDK to integrate with iOS apps.\n\n# Installation\n## Installation with CocoaPods\nTo integrate VelocidiSDK into your Xcode project using [CocoaPods](https://cocoapods.org/), specify it in your `Podfile`:\n\n```yaml\nsource 'https://github.com/CocoaPods/Specs.git'\nplatform :ios, '12.1'\nproject 'MyProject.xcodeproj'\n\ntarget \"MyProject\" do\n  pod 'VelocidiSDK', '~\u003e 0.4.0'\nend\n```\n\nThen, run:\n\n```bash\n$ pod install\n```\n\n## Installation with Carthage\n\nTo integrate VelocidiSDK into your Xcode project using Carthage, specify it in your `Cartfile`:\n\n```\ngithub \"velocidi/velocidi-ios-objc-sdk\" ~\u003e 0.4.0\n```\n\nThen, run `carthage` to build the framework and drag the built VelocidiSDK.framework into your Xcode project.\n\n## Requirements\n\nVelocidiSDK should work with any version of iOS equal or bigger than 10.0.\n\n# Setup\n\nInitialize the VelocidiSDK with the necessary `trackingBaseUrl` and the `matchBaseUrl` URLs. Without this, VelocidiSDK\nwill not work. We suggest doing this when the application launches.\n\n__Swift__\n```swift\nimport VelocidiSDK\n\n@UIApplicationMain\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n\n    var window: UIWindow?\n\n\n    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -\u003e Bool {\n        // Override point for customization after application launch.\n\n        let config = VSDKConfig(trackingBaseUrl: \"https://tr.yourdomain.com\", matchBaseUrl:\"https://match.yourdomain.com\")!\n        VSDKVelocidi.start(config)\n        return true\n    }\n```\n\n__Objective-C__\n```objectivec\n@import VelocidiSDK;\n\n@interface AppDelegate ()\n\n@end\n\n@implementation AppDelegate\n\n\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\n    // Override point for customization after application launch.\n\n    VSDKConfig * config = [[VSDKConfig alloc] initWithTrackingBaseUrl:@\"https://tr.yourdomain.com\" matchBaseUrl: @\"https://match.yourdomain.com\"];\n    [VSDKVelocidi start: config];\n    return YES;\n}\n```\n\n# Send a track event\n\nA tracking event will log a user action in Velocidi's CDP.\n\nIn order to send a tracking event, create a JSON string representation of the event type you wish to send (or a\nequivalent `NSDictionary` representation) and call the `track` method.\n\n__Swift__\n```swift\nimport VelocidiSDK\n\n...\n\nlet trackingEvent =\n\"\"\"\n{\n  \"clientId\": \"bar\",\n  \"siteId\": \"foo\",\n  \"type\": \"appView\",\n  \"customFields\": {\n    \"debug\": \"true\",\n    \"role\": \"superuser\"\n  },\n  \"title\": \"Welcome Screen\"\n}\n\"\"\"\n\n// OR\n\nlet trackingEvent = [\n  \"type\": \"appView\",\n  \"siteId\": \"foo\",\n  \"clientId\": \"bar\",\n  \"title\": \"Welcome Screen\",\n  \"customFields\": [\n    \"debug\": \"true\",\n    \"role\": \"superuser\"\n  ]\n] as [String: Any]\n\nlet userId = VSDKUserId(id: \"user-idfa\", type: \"idfa\")\nVSDKVelocidi.sharedInstance().track(trackingEvent, userId: userId)\n```\n\n__Objective-C__\n```objectivec\n@import VelocidiSDK;\n\n...\n\nNSString * trackingEvent =  @\"\\\n{\\\n  \\\"clientId\\\": \\\"bar\\\",\\\n  \\\"siteId\\\": \\\"foo\\\",\\\n  \\\"type\\\": \\\"appView\\\",\\\n  \\\"customFields\\\": {\\\n    \\\"debug\\\": \\\"true\\\",\\\n    \\\"role\\\": \\\"superuser\\\"\\\n  },\\\n  \\\"title\\\": \\\"Welcome Screen\\\"\\\n}\\\n\";\n\n// OR\n\nNSDictionary *trackingEvent = @{\n  @\"clientId\" : @\"foo\",\n  @\"siteId\" : @\"bar\",\n  @\"type\" : @\"appView\",\n  @\"customFields\" : @{\n    @\"debug\" : @\"true\",\n    @\"role\" : @\"superuser\"\n  },\n  @\"title\" : @\"Welcome Screen\"\n};\n\nVSDKUserId * userId = [[VSDKUserId alloc] initWithId:@\"user-idfa\" type: @\"idfa\"];\n[VSDKVelocidi.sharedInstance track: trackingEvent userId: userId]\n```\n\nPlease refer to https://docs.velocidi.com/collect/events to discover which event types and schemas are supported.\n\nYou can also pass callback blocks that will be called when the request either succeeds or fails.\n\n__Swift__\n```swift\nVSDKVelocidi.sharedInstance().track(trackingEvent, userId: userId, onSuccess:{ (response: URLResponse, responseObject: Any) in\n  print(\"Success! Response: \\(response)\")\n}, onFailure:{(error: Error) in\n  print(\"Failed! Error: \\(error.localizedDescription)\")\n})\n```\n\n__Objective-C__\n```objectivec\n[VSDKVelocidi.sharedInstance track: trackingEvent userId: userId onSuccess: ^(NSURLResponse * response, id responseObject){\n    NSLog(@\"Success! Response: %@\", trackingNumber);\n} onFailure: ^(NSError * error){\n    NSLog(@\"Failed! Error: %@\", [error localizedDescription]);\n}];\n```\n\nThere is a big list of [tracking event types](https://docs.velocidi.com/collect/events) to\nchoose from. If none of them fits the desired action, you can also create your own\n[custom tracking event](https://docs.velocidi.com/collect/events/custom).\n\n# Make a match\n\nMatch requests are used to link multiple identifiers in Velocidi's CDP. This way, any action made with any of the\nidentifiers, across multiple channels (Browser, Mobile App, ...), can be associated to the same user.\n\nIn VelocidiSDK, a match request will link together all the provided user ids:\n\n__Swift__\n```swift\n@IBAction func sendMatchEvent(_ sender: Any) {\n    let userId1 = VSDKUserId(userId: \"bar\", \"fooType\")\n    let userId2 = VSDKUserId(userId: \"baz\", \"fooType\")\n    let idsArray = NSMutableArray(array: [userId1, userId2])\n\n    VSDKVelocidi.sharedInstance().match(\"1234-providerId-56789\", userIds: idsArray, onSuccess:{ (response: URLResponse, responseObject: Any) in\n        print(\"Success! Response: \\(response)\")\n    }, onFailure:{(error: Error) in\n        print(\"Failed! Error: \\(error.localizedDescription)\")\n    })\n}\n```\n\n__Objective-C__\n```objectivec\n- (IBAction)sendMatch:(id)sender {\n    VSDKUserId * userId1 =  [[VSDKUserId alloc] initUserId:@\"bar\":@\"fooType\"];\n    VSDKUserId * userId2 =  [[VSDKUserId alloc] initUserId:@\"baz\":@\"fooType\"];\n    NSMutableArray * idsArray = [[NSMutableArray alloc] initWithObjects: userId1, userId2, nil];\n\n    [VSDKVelocidi.sharedInstance match: @\"1234-providerId-56789\"\n                               userIds: idsArray\n                             onSuccess: ^(NSURLResponse * response, id responseObject){\n        NSLog(@\"Success! Response: %@\", trackingNumber);\n    } onFailure: ^(NSError * error){\n        NSLog(@\"Failed! Error: %@\", [error localizedDescription]);\n    }];\n```\n\n# iOS 14 and collecting IDs\n\nIn iOS 14, Apple changed their privacy guidelines and APIs. We recommend reading Apple's instructions on\n[User Privacy and Data Use](https://developer.apple.com/app-store/user-privacy-and-data-use/).\n\nDue to those changes, the SDK no longer uses the IDFA by default and instead requires the developer to explicitly\ndefine an ID to identify the user. It is up to the developer to choose which user IDs to use, taking in consideration\nthat the ID type should be supported by the CDP system. Refer to our list of\n[supported IDs](https://docs.velocidi.com/collect/user-ids/#default-id-types).\n\n## Using your own first-party ID\n\nYou can use any ID in our list of [supported IDs](https://docs.velocidi.com/collect/user-ids/#default-id-types) with\n[VSDKUserId](https://ios.developers.velocidi.com/Classes/VSDKUtil.html), as exemplified in [Make a Match](#Make-a-match)\nand [Send a tracking event](#Send-a-tracking-event). If you would like to use an ID not present in our list of supported\nIDs, please contact our support so that we can add it.\n\n## Using the IDFV\nThe [Identifier for Vendor (IDFV)](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor)\nis an ID that is shared amongst apps from the same vendor in the same device. It allows a vendor to uniquely identify a\nuser's device, without relying on the device-wide IDFA, and its respective limitations. Per Apple's guidelines _\"The\nIDFV may not be combined with other data to track a user across apps and websites owned by other companies unless you\nhave been granted permission to track by the user\"_.\n\n__Swift__\n```swift\nlet idfv = UIDevice.current.identifierForVendor!.uuidString\nlet userId = VSDKUserId(id: idfv, type: \"idfv\")\n```\n\n__Objective-C__\n```objectivec\nNSString *idfv = [[[UIDevice currentDevice] identifierForVendor] UUIDString];\nVSDKUserId *userId = [[VSDKUserId alloc] initWithId:idfv type:@\"idfv\"];\n```\n\n## Using the IDFA\nIf you are using the Identifier for Advertisers (IDFA) to identify the user, please make sure to read Apple's\ninstructions on [User Privacy and Data Use](https://developer.apple.com/app-store/user-privacy-and-data-use/) and be\nsure that your use case is compliant with Apple's guidelines.\n\nThe following examples should provide a general approach on retrieving the IDFA, but we recommend reading Apple's\ndocumentation on how to use the\n[App Tracking Transparency framework](https://developer.apple.com/documentation/apptrackingtransparency?language=objc).\n\nUsing the IDFA requires explicit authorization from the user for each application. To do so, start by establishing the\nmessage that will be presented to the user in the permission dialog. This can be done by adding the\n__NSUserTrackingUsageDescription__ key to the Info.plist file of the application. The value of this key will be the\nmessage presented.\n\n![tracking usage description entry](./docs/img/ios14_prompt_message.png)\n\nBefore starting to send events, we have to request access to the IDFA, and only if that permission is granted, can we\nsend events with the IDFA. If the user has not given permission yet, this might show the permission dialog box with the\nmessage previously set.\n\n__Swift__\n```swift\nimport AppTrackingTransparency\nimport AdSupport\n\nfunc useIDFA(completionHandler: (Bool, String) -\u003e Void) {\n  if #available(iOS 14, *) { // After iOS 14, we request the IDFA to the AppTrackingTransparency framework\n    ATTrackingManager.requestTrackingAuthorization { status in\n      let isTrackingEnabled = status == .authorized\n      var idfa: String? = nil\n      if isTrackingEnabled {\n        idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString\n      }\n      completionHandler(idfa)\n    }\n  } else { // On older devices, we can access the IDFA directly\n    let isTrackingEnabled = ASIdentifierManager.shared().isAdvertisingTrackingEnabled\n    var idfa: String? = nil\n\n    if isTrackingEnabled {\n      idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString\n    }\n    completionHandler(idfa)\n  }\n}\n```\n\n__Objective-C__\n```objectivec\n#import \u003cAdSupport/ASIdentifierManager.h\u003e\n@import AppTrackingTransparency;\n\n- (void)useIDFA:(void (^)(NSString *))completionHandler {\n  if (@available(iOS 14, *)) { // After iOS 14, we request the IDFA to the AppTrackingTransparency framework\n    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(\n                           ATTrackingManagerAuthorizationStatus status) {\n      bool isTrackingEnabled = status == ATTrackingManagerAuthorizationStatusAuthorized;\n      NSString *idfa = nil;\n      if (isTrackingEnabled) {\n        idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];\n      }\n      completionHandler(idfa);\n    }];\n  } else { // On older devices, we can access the IDFA directly\n    bool isTrackingEnabled = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled];\n    NSString *idfa = nil;\n    if (isTrackingEnabled) {\n      idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];\n    }\n    completionHandler(idfa);\n  }\n}\n```\n\nOnce we established a method of requesting permission for using the IDFA, we just have to call it and provide a\ncompletion handler where we are creating the event.\n\n__Swift__\n```swift\nuseIDFA(completionHandler: { (idfaOpt) in\n  if let idfa = idfaOpt {\n    let userId = VSDKUserId(id: idfa, type: \"idfa\")\n    // ...\n  }\n})\n```\n\n__Objective-C__\n```objectivec\n[self useIDFA:^(NSString *idfa) {\n  if (idfa != nil) {\n    VSDKUserId *userId = [[VSDKUserId alloc] initWithId:idfa type:@\"idfa\"];\n    // ...\n  }\n}];\n```\n\n# Need Help?\n\nYou can find more information about Kevel Audience at https://docs.audience.kevel.com.\n\nPlease report bugs or issues to https://github.com/adzerk/velocidi-ios-objc-sdk/issues or send us an email to\nkdp-engineering@kevel.co.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzerk%2Faudience-ios-objc-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadzerk%2Faudience-ios-objc-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzerk%2Faudience-ios-objc-sdk/lists"}