Please see our Release Notes to see detailed version history.

For Unity-specific instructions, please visit https://github.com/tenjin/tenjin-unity-sdk.

Tenjin iOS SDK (v1.7.5) (268KB) (Deployment Version 6.0+)

Note: We recommend using the latest version of Xcode when integrating our SDK.

Tenjin initialization:

• If you use pods add pod 'TenjinSDK' to your Podfile then run pod install and skip to step 5!

1. Download the SDK's contents here

2. Drag libTenjinSDK.a and TenjinSDK.h to your project. Note: If you are testing with 32-bit iOS Simulator devices (i386), you will need to use libTenjinSDKUniversal.a instead of libTenjinSDK.a.

3. Add the following Frameworks to your project:

• AdSupport.framework
• StoreKit.framework
• iAd.framework

4. Include the linker flags -ObjC under your Build Settings

5. Go to your AppDelegate file, by default AppDelegate.m, and #import "TenjinSDK.h".

6. Get your API_KEY from your Tenjin Organization tab.

7a. In your didFinishLaunchingWithOptions method add:

[TenjinSDK init:@"<API_KEY>"];
[TenjinSDK connect];

Here's an example of what your integration should look like in your AppDelegate.m file:

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [TenjinSDK init:@"<API_KEY>"];
    [TenjinSDK connect];

    //All your other stuff
    ...
}

7b. Alternate initialization to handle deep links from other services. (DO NOT USE 7a and 7b. You need to use only one.)

If you use other services to produce deferred deep links, you can pass Tenjin those deep links to handle the attribution logic with your Tenjin enabled deep links.

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  
    [TenjinSDK init:@"<API_KEY>"];

    //get your deep link from your other 3rd party service
    NSURL *url = [NSURL withString: @"your_deep_link"];
    
    //if you have a deep link that's generated from a third party service then pass it to tenjin to handle the attribution of deep links holistically
    if(url) {
      [TenjinSDK connectWithDeferredDeeplink:url];
    }
    else{
      [TenjinSDK connect];
    }

    //All your other stuff
    //...
}

8. Validate your live events by adding your Test Device and observing your events come through in the live Tenjin Diagnostic tab.

Tenjin and GDPR:

As part of GDPR compliance, with Tenjin's SDK you can opt-in, opt-out devices/users, or select which specific device-related params to opt-in or opt-out. OptOut() will not send any API requests to Tenjin and we will not process any events.

To opt-in/opt-out:

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  
  [TenjinSDK init:@"<API_KEY>"];

  if ([self checkOptInValue]) {
      [TenjinSDK optIn];
  }
  else {
      [TenjinSDK optOut];
  }

  [TenjinSDK connect];

  //All your other stuff
  //..
}

-(BOOL) checkOptInValue
{
  // check opt-in value
  // return YES; // if user opted-in
  return NO;
}

To opt-in/opt-out specific device-related parameters, you can use the OptInParams() or OptOutParams(). OptInParams() will only send device-related parameters that are specified. OptOutParams() will send all device-related parameters except ones that are specified. Please note that we require at least ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer (Android), and iad (iOS) to properly track devices in Tenjin's system.

If you want to only get specific device-related parameters, use OptInParams(). In example below, we will only these device-related parameters: ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer, and iad:

[TenjinSDK init:@"<API_KEY>"];

NSArray *optInParams = @[@"ip_address", @"advertising_id", @"developer_device_id", @"limit_ad_tracking", @"referrer", @"iad"];
[TenjinSDK optInParams:optInParams];

[TenjinSDK connect];

If you want to send ALL parameters except specfic device-related parameters, use OptOutParams(). In example below, we will send ALL device-related parameters except: locale, timezone, and build_id parameters.

[TenjinSDK init:@"<API_KEY>"];

NSArray *optOutParams = @[@"country", @"timezone", @"language"];
[TenjinSDK optOutParams:optOutParams];

[TenjinSDK connect];

Device-Related Parameters

Param	Description	Reference
advertising_id	Device Advertising ID	iOS
developer_device_id	ID for Vendor	iOS
limit_ad_tracking	limit ad tracking enabled	iOS
platform	platform	iOS
iad	Apple Search Ad parameters	iOS
os_version	operating system version	iOS
device	device name	iOS (hw.machine)
device_model	device model	iOS (hw.model)
device_model_name	device machine	iOS (hw.model)
device_cpu	device cpu name	iOS (hw.cputype)
os_version_release	operating system version	iOS
build_id	build ID	iOS (kern.osversion)
locale	device locale	iOS
country	locale country	iOS
timezone	timezone	iOS

Tenjin purchase event integration instructions:

There are two ways to handle revenue events:

1. Pass (SKPaymentTransaction *) transaction and (NSData *)receipt object:

After a purchase has been verified and SKPaymentTransactionStatePurchased you can pass Tenjin the transaction which was purchased:

//Get the NSData receipt
NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL];

//Pass the transaction and the receiptData to Tenjin
[TenjinSDK transaction: transaction andReceipt: receiptData];

If you have subscription receipts, please be sure to add your IAP shared secret to your appropriate app in the Tenjin Apps Dashboard. Please note that you are responsible to send subscription transaction one time during each subscription interval (i.e. For example, for a monthly subscription, you will need to send us 1 transaction per month).

OR

2. Pass a transaction manually (usually this is necessary if purchases are not handled by Apple):

To use this method, you will need a productName, currencyCode, quantity, and the unit price of the transaction:

NSString *productName = @"product_1";
NSString *currencyCode = @"USD";
NSDecimalNumber *price = [NSDecimalNumber decimalNumberWithString:@"0.99"];
NSInteger quantity = 1;

[TenjinSDK  transactionWithProductName: productName
            andCurrencyCode: currencyCode
            andQuantity: quantity
            andUnitPrice: price];

• ProductName -> The name or ID of your product
• CurrencyCode -> The currency of your unit price
• Quantity -> The number of products that are counted for this purchase event
• UnitPrice -> The price of each product

Total Revenue calculated is: TotalRevenue = Quantity * UnitPrice

Tenjin custom event integration instructions:

NOTE: DO NOT SEND CUSTOM EVENTS BEFORE THE INITIALIZATION event (above). The initialization must come before any custom events are sent.

You can also use the Tenjin SDK to pass a custom event:

• sendEventWithName: (NSString *)eventName and

You can use these to pass Tenjin custom interactions with your app to tie this to user level cost from each acquisition source that you use through Tenjin's platform. Here are some examples of usage:

//send a particular event for when someone swipes on a part of your app
[TenjinSDK sendEventWithName:@"swipe_right"];

Custom events can also pass an NSString eventValue. Tenjin will use this eventValue as a count or sum for all custom events with the same eventName. The eventValue MUST BE AN INTEGER. If the eventValue is not an integer, we will not send the event.

Tenjin deferred deeplink integration instructions:

Tenjin supports the ability to direct users to a specific part of your app after a new attributed install via Tenjin's campaign tracking URLs. You can utilize the registerDeepLinkHandler handler to access the deferred deeplink through params[@"deferred_deeplink_url"] that is passed on the Tenjin campaign tracking URLs. To test you can follow the instructions found here.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //initialize the Tenjin SDK like you normally would for attribution
    [TenjinSDK init:@"<API_KEY>"];
    [TenjinSDK connect]

    //If you want to utilize the deeplink capabilities in Tenjin, utilize the registerDeepLinkHandler to retrieve the deferred_deeplink_url from the params NSDictionary object
    [[TenjinSDK sharedInstance] registerDeepLinkHandler:^(NSDictionary *params, NSError *error) {
        if([params[@"clicked_tenjin_link"] boolValue]){
            if([params[@"is_first_session"] boolValue]){
                
                //use the params to retrieve deferred_deeplink_url through params[@"deferred_deeplink_url"]
                //use the deferred_deeplink_url to direct the user to a specific part of your app
                
            } else{

            }
        }
    }];
}

You can also use the v1.7.2+ SDK for handling post-install logic using the params provided in this registerDeepLinkHandler. For example, if you have a paid app, you can register your paid app install in the following way:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //initialize the Tenjin SDK like you normally would for attribution
    [TenjinSDK init:@"<API_KEY>"];
    [TenjinSDK connect]

    //If you want to utilize the deeplink capabilities in Tenjin, utilize the registerDeepLinkHandler to retrieve the deferred_deeplink_url from the params NSDictionary object
    [[TenjinSDK sharedInstance] registerDeepLinkHandler:^(NSDictionary *params, NSError *error) {
        
          if([params[@"is_first_session"] boolValue]){
              //send paid app price and revenue to Tenjin
              
          } else{

          }
        
    }];
}