Quickstart

1. SDK Integration

A. Cocoapods

CocoaPods is a dependency manager for Objective-C and Swift.

To use Tapjoy simply add it to your podfile:

    platform :ios, '10.0'
    source 'https://github.com/CocoaPods/Specs.git'

    use_frameworks!

    target 'MyApp' do
        pod 'TapjoySDK'
    end

When integrating via Cocoapods we provide the option of either a static or dynamic framework. The default is static. You can add the following to your podfile to choose the dynamic framework:

pod 'TapjoySDK/Dynamic'

B. Swift Package Manager

As of SDK v13.4.0 we support Swift Package Manager.

Go to File > Add Packages Dependancies. In the top right search bar paste the repo https://github.com/Tapjoy/swift-packages.git and choose Add Package.

2. Request App Tracking Transparency authorization

If your application is designed to use App Tracking Transparency, to display the dialog to request permission for accessing the IDFA, update your Info.plist by including the NSUserTrackingUsageDescription key along with a custom message to describe this permission to use IDFA in your application.

For example:

<key>NSUserTrackingUsageDescription</key>
<string>This allows us to deliver personalized ads for you.</string>

The usage description text will then appear as part of the App Tracking Transparency permission dialog, as shown in the screenshot below:

Add the AppTrackingTransparency framework to your project, and then call requestTrackingAuthorizationWithCompletionHandler: to display the authorization prompt. As a best practice, we recommend that you wait for the requestTrackingAuthorization completion handler before connecting to Tapjoy so that we can be assured we are using the expected IDFA value in all requests.

#import <AppTrackingTransparency/AppTrackingTransparency.h>
...
- (void)fetchTrackingAuthorization {
  [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
    // Call Tapjoy's connect function here.
  }];
}

3. Connect to Tapjoy

The next step is to add the Tapjoy connect code to your application. This key bit of code "turns on" the Tapjoy SDK in your application.

The Tapjoy connect call is extremely important, as none of Tapjoy’s products or functionality will work if it is not implemented correctly.

To implement the Tapjoy connect call, you will need your Tapjoy SDK Key for the application you are integrating. To find this, navigate to your application in the Tapjoy dashboard, and click the "Settings" button on the top navigation bar. Navigate to "App Settings" and you will find the SDK Key at the bottom of the page.

Now, place the following snippet of code into the application:didFinishLaunchingWithOptions method in your application’s app delegate file:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(tjcConnectSuccess:) name:TJC_CONNECT_SUCCESS object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(tjcConnectFail:) name:TJC_CONNECT_FAILED object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(tjcConnectWarning:) name:TJC_CONNECT_WARNING object:nil];

    //Turn on Tapjoy debug mode
    [Tapjoy setDebugEnabled:YES]; //Only enable debug mode for development. Disable it before publishing your app.

    //If you are using Self-Managed currency, you need to set a user ID using the connect flags.
    NSDictionary *connectFlags = @{TJC_OPTION_USER_ID : @"<USER_ID_HERE>"};
    [Tapjoy connect:@"SDK_KEY_GOES_HERE" options:connectFlags];
    
    //If you are not using connect flags, you can omit them
    [Tapjoy connect:@"SDK_KEY_GOES_HERE"];

    return YES;
}

The method setDebugEnabled should be defined before the connect call. We recommend setting a user ID via the connect flags. This allows for the AppLaunch placement to retrieve the correct user ID when called.

More information can be found in our SDK references: Objective C and C++.

Connect Notifications

To receive a notification when Tapjoy has finished connecting, connected with a warning, or failed to connect you need to implement the methods we previously set as selectors. The connectWarning callback will fire when there is a non-blocking issue during connect (andconnectSuccess will also fire after). Currently this feature will only detect issues with UserId when sent in ConnectFlags.

- (void)tjcConnectSuccess:(NSNotification *)notifyObj 
{
    NSLog(@"Tapjoy connect succeeded");
}

- (void)tjcConnectFail:(NSNotification *)notifyObj 
{
    NSError *error = notifyObj.userInfo[TJC_CONNECT_USER_INFO_ERROR];
    NSInteger code = error.code;
    NSString *message = error.localizedDescription;
    NSString *underlyingErrorMessage = underlyingError != nil ? [NSString stringWithFormat:@" - %li %@", underlyingError.code, underlyingError.localizedDescription] : @""; 
    NSLog(@"%@", underlyingErrorMessage);
}

- (void)tjcConnectWarning:(NSNotification *)notifyObj 
{
    NSError *error = notifyObj.userInfo[TJC_CONNECT_USER_INFO_ERROR];
    NSError *underlyingError = error.userInfo[NSUnderlyingErrorKey];
}

Now compile and run your application. If you have done everything correctly, you should see output on the console log similar to the following:

        2020-01-29 16:01:55.422 App Name[25869:1433019] [TJLog level: 4] Connect success with type:0

Congratulations! You now have Tapjoy working in your application.

Max User Level

You can tell Tapjoy how many levels there are in your game. You can set this value before or after calling connect.

[Tapjoy setMaxLevel:10]; 

User Segment

You can identify users as part of a segment by calling setUserSegment. This can be set before or after calling connect.

[Tapjoy setUserSegment:TJSegmentVIP];
[Tapjoy setUserSegment:TJSegmentPayer];
[Tapjoy setUserSegment:TJSegmentNonPayer];
[Tapjoy setUserSegment:TJSegmentUnknown];