Admitad SDK for iOS

iOS integration SDK of https://www.admitad.com/

Admitad help center: https://help.admitad.com/en/advertiser/topic/195-mobile-sdk/

⚠️Note⚠️ If you need Swift 4, use pod version <= 1.1.4.

Table of contents

• Setting your project
• Manual Installation
• Installation via CocoaPods
• Alamofire version
• Objective-C interoperability
• Setting AppDelegate
• Event Tracking
  • User Id
  • Register
  • Returned
  • Loyalty
  • Order
    • Additional parameters
    • Confirmed Purchase
    • Paid Order
  • Events deduplication
• Delegation and Callbacks
• License

Setting your project

Make sure that your project's deployment target is iOS 9.0 or higher.

Your project should be set up to make interaction with URL Schemes and Universal Links possible. Note: you also should test on a real device because deeplinking doesn't work on simulator and therefore most of AdmitadSDK functionality won't be available.

Important AdmitadSDK uses version 4.x of Alamofire as a dependency. So if you use Alamofire in your project, it's major release number should be 4. You're free to specify any minor release number for your needs. The link below contains fully descriptive manual on Alamofire installation process: Alamofire GitHub Page

To add AdmitadSDK to your project you have two options:

1. Manual Installation
2. Installation via CocoaPods

Manual Installation

To add AdmitadSDK itself please follow these steps:

1. Clone this repository or download zip-file.
2. Drag and drop the AdmitadSDK.xcodeproj to Project Navigator in Xcode of your application's Xcode project.
3. In your project, reveal the 'AdmitadSDK.xcodeproj > Products' hierarchy. Then drag the Admitad.framework product to the 'Embedded Binaries' section of your build product.

Installation via CocoaPods

If you have CocoaPods installed (installation process is described here) do the following:

1. cd to the directory where your project is located.
2. run pod init in Terminal. A Podfile will be created.
3. Modify the Podfile to look like this:

   platform :ios, '9.0'
   use_frameworks!
   
   target '<Your Target>' do
       pod 'AdmitadSDK'
   end

4. Run pod install. A .xcworkspace will be created.
5. Close your project (if opened) and open the .xcworkspace.
6. If you've run into some issues installing AdmitadSDK via CocoaPods, try running pod update in Terminal.

Objective-C interoperability

Just add @import AdmitadSDK; import statement to the source files that make use of AdmitadSDK.

Setting AppDelegate

1. Get a Singleton AdmitadTracker Instance.
   All sdk methods require an instance of the main AdmitadTracker object. Here's how you can get one. It's stored statically and is accessible from any class.

   Swift:

   let admitadTracker = AdmitadTracker.sharedInstance

   Objective-C:

   AdmitadTracker *admitadTracker;

2. In application(_:didFinishLaunchingWithOptions:) method assign AdmitadTracker singleton's postbackKey property to your Admitad Postback Key.

3. In the same method call AdmitadTracker's trackAppLaunch(), trackReturnedEvent() и trackLoyaltyEvent().

   Swift:

   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
   
   admitadTracker.postbackKey = "postbackKey"
   
   admitadTracker.trackAppLaunch()
   admitadTracker.trackReturnedEvent()
   admitadTracker.trackLoyaltyEvent()
   
   return true
   }

   Objective-C:

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   
   admitadTracker = [AdmitadTracker sharedInstance];
   
   admitadTracker.postbackKey = @"postbackKey";
   
   [admitadTracker trackAppLaunchWithChannel:nil];
   [admitadTracker trackReturnedEventWithUserId:nil channel:nil completion:nil];
   [admitadTracker trackLoyaltyEventWithUserId:nil channel:nil completion:nil];
   
   return YES;
   }
   

4. To track Universal Links usage, in application(_:continue:restorationHandler:) call corresondingly named continueUserActivity method and pass userActivity to it as parameter.

   Swift:

   func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
   admitadTracker.continueUserActivity(userActivity)
   return true
   }

   Objective-C:

   - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {
   
   [admitadTracker continueUserActivity:userActivity];
   return YES;
   }

5. To track URL Schemes usage, in application(_:open:options:) call openUrl method and pass url to it as parameter.

   Swift:

   func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
   admitadTracker.openUrl(url)
   return true
   }

   Objective-C:

   - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
   
   [tracker openUrl:url];
   return YES;
   }

6. To get current uid:

   let uid = admitadTracker.getUid();

   NSString* uid = [tracker getUid];  

Event Tracking

If you have setup your AppDelegate right, Installed event is triggered automatically,

Methods trackRegisterEvent(), trackReturnedEvent() and trackLoyaltyEvent() can take user ID as parameter. Optionally you can setup AdmitadTracker singleton's userId property. If you prefer not to provide user ID in any of these ways, user ID will be generated automatically.

User Id

Swift:

// somewhere in your code
admitadTracker.userId = userId

Objective-C:

// somewhere in your code
admitadTracker.userId = userId

Register

Register event are triggered when:

Swift:

admitadTracker.trackRegisterEvent()

or

admitadTracker.trackRegisterEvent(userId: userId)

Objective-C:

[admitadTracker trackRegisterEventWithUserId:nil channel:nil completion:nil];

or

[admitadTracker trackRegisterEventWithUserId: userId channel:nil completion:nil];

Returned

Returned event are triggered when:

Swift:

admitadTracker.trackReturnedEvent()

or

admitadTracker.trackReturnedEvent(userId: userId)

Objective-C:

[admitadTracker trackReturnedEventWithUserId:nil channel:nil completion:nil];

or

[admitadTracker trackReturnedEventWithUserId: userId channel:nil completion:nil];

Loyalty

Loyalty event are triggered when:

Swift:

admitadTracker.trackLoyaltyEvent()

or

admitadTracker.trackLoyaltyEvent(userId: userId)

Objective-C:

[admitadTracker trackLoyaltyEventWithUserId:nil channel:nil completion:nil];

or

[admitadTracker trackLoyaltyEventWithUserId: userId channel:nil completion:nil];

Order

To track Confirmed Purchase and Paid Order an AdmitadOrder object must be instantiated and passed as parameter to trackConfirmedPurchaseEvent or trackPaidOrderEvent respectively.

Swift:

let items = [AdmitadOrderItem(name: "Phone"), AdmitadOrderItem(name: "Phone Charger", quantity: 3)]

let order = AdmitadOrder(id: id, totalPrice: price, currencyCode: currencyCode, items: items, userInfo: userInfo)

Objective-C:

AdmitadOrderItem *item1 = [[AdmitadOrderItem alloc] initWithName:@"Phone"
quantity:1];
AdmitadOrderItem *item2 = [[AdmitadOrderItem alloc] initWithName:@"Phone Charger"
quantity:3];

NSArray<AdmitadOrderItem *> *items = @[item1, item2];

AdmitadOrder *order = [[AdmitadOrder alloc] initWithId:id totalPrice:price currencyCode:currencyCode items:items userInfo:userInfo];

Additional parameters

• You can customize your order using any combination of additional parameters.

tarifCode

You can initialize AdmitadOrder with extra parameter tarifCode. Then Admitad can apply this tariff to the order as defined in your agreement. To get tariff codes ask your Admitad account manager.

Swift:

let orderWithTarif = AdmitadOrder(id: id, totalPrice: price, currencyCode: currencyCode, items: items, userInfo: userInfo, tarifCode: "itemCategory1")

Objective-C:

AdmitadOrder *orderWithTarif = [[AdmitadOrder alloc] initWithId:id totalPrice:price currencyCode:currencyCode items:items userInfo:userInfo tarifCode:tarifCode];

promocode

You can initialize AdmitadOrder with extra parameter promocode. Then Admitad will show promocode for this order in statistics report of your campaign.

Swift:

let orderWithPromocode = AdmitadOrder(id: id, totalPrice: price, currencyCode: currencyCode, items: items, userInfo: userInfo, promocode: "SUPER_PROMO")

Objective-C:

AdmitadOrder *orderWithPromocode = [[AdmitadOrder alloc] initWithId:id totalPrice:price currencyCode:currencyCode items:items userInfo:userInfo promocode:promocode];

Confirmed Purchase

Swift:

admitadTracker.trackConfirmedPurchaseEvent(order: order)

Objective-C:

[admitadTracker trackConfirmedPurchaseEventWithOrder:order channel:nil completion:nil];

Paid Order

Swift:

admitadTracker.trackPaidOrderEvent(order: order)

Objective-C:

[admitadTracker trackPaidOrderEventWithOrder:order channel:nil completion:nil];

Events deduplication

• You can pass extra parameter channel into methods that track events. It's value will be used for deduplication on Admitad's side. Set channel value to:
  • AdmitadTracker.ADMITAD_MOBILE_CHANNEL if you intend to attribute event to Admitad
  • name of other affiliate network if you intend to attribute event to other network
  • AdmitadTracker.UNKNOWN_CHANNEL if you don't know to whom the event should be attributed

For example, set attribution channel for confirmed purchase In-App Event: Swift:

admitadTracker.trackConfirmedPurchaseEvent(order: order, channel: AdmitadTracker.ADMITAD_MOBILE_CHANNEL)

Objective-C:

[admitadTracker trackConfirmedPurchaseEventWithOrder:order channel:@"some_network" completion:nil];

Delegation and Callbacks

When working with AdmitadSDK from Swift environment you are provided with two mechanisms of notification on event tracking success or failure. Every event triggering method takes a completion callback. In the callback you can check if an error has occurred. AdmitadTracker instance also notifies its delegate object conforming to AdmitadDelegate protocol. Both ways of notification are independent from each other and can be used simultaneously and interchangeably. In Objective-C environment only the former mechanism is available.

Swift:

class YourClass: AdmitadDelegate {
    func someFunc() {
        AdmitadTracker.sharedInstance.delegate = self
    }

    func startedTrackingAdmitadEvent(_ event: AdmitadEvent) {
        // code on start tracking
    }

    func finishedTrackingAdmitadEvent(_ event: AdmitadEvent?, error: AdmitadError?) {
        // code on finished tracking
        // you can check if error is nil here
    }
}

or

trackRegisterEvent() { error in
    // code on finished tracking
    // you can check if error is nil here
}

Objective-C:

[admitadTracker trackRegisterEventWithUserId:nil channel:nil completion:^(AdmitadError *error) {
    // code on finished tracking
    // you can check if error is nil here
}];

License

The admitad SDK is licensed under the MIT License.

Copyright (c) 2017 Admitad GmbH

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.