Skip to content

Latest commit

 

History

History
271 lines (197 loc) · 12.3 KB

README.md

File metadata and controls

271 lines (197 loc) · 12.3 KB

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

Dashboard

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

Dashboard

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{

          }
        
    }];
}