Manual Integration

1. Download SDK

The first step in integrating with your app is to download the iOS SDK itself.

2. Add the SDK to Your Project

After unzipping the SDK, you find docs, libraries and the TapjoyEasyApp.

The “TapjoyEasyApp” is a sample project that demonstrates the Tapjoy integration. You do not need it for integrating Tapjoy into your own application but it is a useful reference.

To add the files to your project, choose ‘File’ and ‘Add files to Project’. Navigate to the "Libraries" folder and select the Tapjoy.xcframework (or Tapjoy.embeddedframework if you are using an older version of Tapjoy) folder. Make sure to select ‘copy items if needed’ in the dialog and then click ‘Add’.

If you are using Tapjoy 12.8.0 or later:

  • Navigate to Other Linker Flags (OTHER_LDFLAGS) in your build settings.

  • Add the -ObjC flag.

A. Add Required Frameworks

The next step is to add the required frameworks to your project. To do this, click on your project icon in the Project Navigator, then select "Build Phases", expand "Link Binary With Libraries", and click the "+" symbol in the lower left of the section. Frameworks are listed alphabetically and you can hold the CMD key to select multiple frameworks, allowing you to add them in one step.

Add all of the following frameworks to your project:

  • AdSupport
  • CFNetwork
  • CoreTelephony
  • StoreKit
  • SystemConfiguration
  • UIKit
  • WebKit
  • libc++
  • libz
  • PassKit (can be marked 'Optional' for compatibility with older versions of iOS)

NB: If you are using a version of Tapjoy SDK older than 12.8.0 you must also include the following frameworks:

  • CoreGraphics
  • Foundation
  • ImageIO.framework
  • MediaPlayer
  • MobileCoreServices
  • QuartzCore
  • Security

B. Swift

If you are using Tapjoy SDK 12.8.0 or later this step is not necessary.

To use Tapjoy in Swift you need to create a bridging header.

  1. Create a new header file and name it: "[ProjectName]-Bridging-Header.h"
  2. Add #import "Tapjoy/Tapjoy.h to the bridginer header.
  3. Finally go to your targets build settings, search for "bridging header" and set the file path. You can do this easily by dragging and dropping the file from your project navigation hierarchy into the text field.

3. Enable SKAdNetwork

Tapjoy is enrolled as a network partner in Apple’s SKAdNetwork. Add Tapjoy's network ID to your app’s info.plist file along with the IDs of the DSP partners. These are available in both XML and JSON formats:

More info here.

4. 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>

image_title

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

image_title

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.

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

5. 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:

Objective-C
Swift
- (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];

    //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 would set your own user ID here.
    [Tapjoy setUserID:@"A_UNIQUE_USER_ID"];
    
    //The Tapjoy connect call
    [Tapjoy connect:@"Your-iOS-SDK-Key-from-the-dashboard-goes-here"];

    return YES;
}

The method’s setDebugEnabled and setUserID should be defined before the connect call. Setting a user ID prior to connect allows for the AppLaunch placement to retrieve the correct user ID when called, and is also required for Push2Earn placements.

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

6. Connect Notifications

To receive a notification when Tapjoy has finished connecting (or failed to connect) you need to implement the methods we previously set as selectors:

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

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

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 Storyteller Roller[25869:1433019] [TJLog level: 4] Connect success with type:0

In the Tapjoy Dashboard, if you click on "Analytics" in the top navigation bar and then the "Real-time" tab in the navigation bar on the left, you should see some activity from your application moments after you run it.

Congratulations! You now have Tapjoy working in your application.