NAV Navbar
Logo
swift objective_c

Introduction

Welcome to Kitemetrics! You can use Kitemetrics to attribute iOS App installs to Apple Search Ads. Attribution data includes the keyword, ad group, campaign, and organization. In addition, you can link in-app purchases and other events to automatically calculate the Average Revenue per User and Return on Investment per keyword.

The Kitemetrics iOS Client SDK is open source and available at https://github.com/kitefaster/kitemetrics_iOS.

Requirements

Authentication

Kitemetrics uses an API Key for authentication. Each organization has a single API Key which can be used for multiple apps in the organizations app portfolio. Sign up for a free account at https://cloud.kitemetrics.com/register and then create an Organization to obtain the API Key. You can always view the API Key by going to Account Settings / Organizations / and then selecting your Organization.

Installation

CocoaPods

$ gem install cocoapods
platform :ios, '8.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'Kitemetrics'
end

Make sure to replace <Your Target Name> with your actual target name.

$ pod install

CocoaPods is a dependency manager for Cocoa projects. You can install CocoaPods with the gem install cocoapods command. Note that CocoaPods 1.1.0+ is required to build Kitemetrics.

To integrate Kitemetrics into your Xcode project using CocoaPods, specify it in your Podfile with pod 'Kitemetrics'

Then, run the following pod install.

To update an existing Kitemetrics pod to the latest version use pod update Kitemetrics

Manually

If you do not want to use the CocoaPods dependency manager, you can integrate Kitemetrics into your project manually by adding it as a git submodule or by copy/pasting the files into your project.

Initialization

import Kitemetrics

class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
      Kitemetrics.shared.initSession(apiKey: "API_KEY")
      return true
  }
@import Kitemetrics;

@interface AppDelegate ()

@end

@implementation AppDelegate


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[Kitemetrics shared] initSessionWithApiKey:@"API_KEY"];
    return YES;
}

Don’t forget to replace API_KEY with your organizations Kitemetrics API Key.

The sample code on the right is in Swift by default. To toggle between Swift and Objective-C use the tab at the top right of the page.

Initialize the session in AppDelegate application:didFinishLaunchingWithOptions: with the following code.

Kitemetrics.shared.initSession(apiKey: "API_KEY").

If a user identifier is known on app launch you can use the optional parameter userIdentifier. For example:

Kitemetrics.shared.initSession(apiKey: "API_KEY", userIdentifier: "User12345").

The userIdentifier is used to track the number of active users as opposed to the number of active devices.

Events

Purchase

    Kitemetrics.shared.logInAppPurchase(skProduct, quantity: 1)
    //It is recommended to include the purchaseType if known
    Kitemetrics.shared.logInAppPurchase(skProduct, quantity: 1, purchaseType: KFPurchaseType.appleInAppNonConsumable)

    //If the SKProduct is unavailable you can log a purchase directly as
    Kitemetrics.shared.logPurchase(productIdentifier: "productId", price: Decimal(0.99), currencyCode: "USD", quantity: 1, purchaseType: .eCommerce)
    [[Kitemetrics shared] logInAppPurchase:skProduct quantity:1];
    //It is recommended to include the purchaseType if known
    [[Kitemetrics shared] logInAppPurchase:skProduct quantity:1 purchaseType:KFPurchaseTypeAppleInAppNonConsumable];

    //If the SKProduct is unavailable you can log a purchase directly as
    NSDecimal price = [[[NSDecimalNumber alloc] initWithFloat:0.99f] decimalValue];
    [[Kitemetrics shared] logPurchaseWithProductIdentifier:@"productId" price:price currencyCode:@"USD" quantity:1 purchaseType:KFPurchaseTypeECommerce];

Log purchases with the SKProduct after an in-app purchase is completed and verified. This is required to compute reports such as Average Revenue per User and Return on Investment.

It is recommended to include the purchase type if it is known. Including the purchase type can help reduce duplicate non-consumable purchases being recorded by the same device in the case of a connection error or the user restoring their purchase later. Below are the corresponding types to use with KFPurchaseType:

In-App Purchase Type KFPurchaseType
Consumable .appleInAppConsumable
Non-Consumable .appleInAppNonConsumable
Auto-Renewable Subscriptions .appleInAppAutoRenewableSubscription
Non-Renewing Subscriptions .appleInAppNonRenewingSubscription

For eCommerce transactions that are not subject to Apple’s 30% commission you can use KFPurchaseType.eCommerce.

Auto-Renewable Subscriptions

For auto-renewable subscriptions you will need to log a new purchase event with the purchaseType set to .appleInAppAutoRenewableSubscription every time the user auto-renews the subscription. Be sure to only log the purchase event once per renewal period.

    Kitemetrics.shared.logInAppPurchase(skProduct, quantity: 1, purchaseType: .appleInAppAutoRenewableSubscription)
    //or
    Kitemetrics.shared.logPurchase(productIdentifier: "productId", price: Decimal(0.99), currencyCode: "USD", quantity: 1, purchaseType: .appleInAppAutoRenewableSubscription)
    [[Kitemetrics shared] logInAppPurchase:skProduct quantity:1 purchaseType:KFPurchaseTypeAppleAutoRenewableSubscription];
    //or
    NSDecimal price = [[[NSDecimalNumber alloc] initWithFloat:11.99f] decimalValue];
    [[Kitemetrics shared] logPurchaseWithProductIdentifier:@"productId" price:price currencyCode:@"USD" quantity:1 purchaseType:KFPurchaseTypeAppleAutoRenewableSubscription];

SignUp

    Kitemetrics.shared.logSignUp(method: "email", userIdentifier: "012345abc")
    [[Kitemetrics shared] logSignUpWithMethod:@"email" userIdentifier:@"012345abc"];

Log sign ups to track the number of new users instead of just active devices.

Add To Cart

    Kitemetrics.shared.logInAppAddToCart(skProduct, quantity: 1)
    //or
    Kitemetrics.shared.logAddToCart(productIdentifier: "productId", price: Decimal(0.99), currencyCode: "USD", quantity: 1, purchaseType: .eCommerce)
    [[Kitemetrics shared] logAddToCartWithProductIdentifier:(NSString * _Nonnull) price:(NSDecimal) currencyCode:(NSString * _Nonnull) quantity:(NSInteger) purchaseType:(enum KFPurchaseType)];

Log add to cart with the SKProduct when the user shows intent to make an in-app purchase. Reports for add to cart are still under development.

Invite

    Kitemetrics.shared.logInvite(method: "textMessage", code: "Test Code 001")

    Kitemetrics.shared.logRedeemInvite(code: "Test Code 001")
    [[Kitemetrics shared] logInviteWithMethod:@"textMessage" code: @"Test Code 001"];

    [[Kitemetrics shared] logRedeemInviteWithCode:@"Test Code 001"];

Log invites along with the method used to send them and a unique redemption code to track the virality of your application. Also log when the invite code is redeemed. Reports for invites are still under development.

Custom Event

    Kitemetrics.shared.logEvent("Test Event")
    [[Kitemetrics shared] logEvent:@"Test Event"];

Log custom events. Reports for custom events are still under development.

Custom Error

    Kitemetrics.shared.logError("Test Error")
    [[Kitemetrics shared] logError:@"Test Error"];

Log custom errors. Reports for custom errors are still under development.

Example

$ git clone https://github.com/kitefaster/kitemetrics_iOS.git
$ cd kitemetrics_iOS/Example
$ pod install
$ git clone https://github.com/kitefaster/kitemetrics_iOS.git
$ cd kitemetrics_iOS/Example_Objective-C
$ pod install

To run the example project, clone the repo at https://github.com/kitefaster/kitemetrics_iOS, and run pod install from the Example (Swift) or the Example_Objective-C directory first.

Notes

Kitemetrics uses the Advertising Identifier (IDFA). When submitting an app to Apple you should answer Yes to the Advertising Identifier question and check the box next to “Attribute an action taken within this app to a previously served advertisement”.

Support

Email support@kitemetrics.com with any questions, suggestions, or feedback.

License

The Kitemetrics iOS client SDK is available under the Apache License, Version 2.0. See the LICENSE file for more info.