This page describes how to integrate the Tapjoy SDK into your iOS application if you are using Tapjoy for Pay-Per-Install (PPI or CPI) campaigns.
PPE (Pay Per Engagement) campaigns
If you are using Tapjoy to integrate a PPE campaign (also known as PPA or CPE), you need to follow some additional steps after completing the steps in this guide.
Note that if you are also publishing with Tapjoy (i.e. using it for analytics or to show ads or messages) you can simply follow the integration instructions for Publishers. If you follow those instructions, you will have done everything necessary for the Tapjoy campaign tracking to work. Please see the Getting Started Guide iOS for Publishers.
Tapjoy iOS SDK requirements:
- iOS 8.0 or greater
- You should use Xcode 9.3 or later
The first thing you need to do is set up your application on the Tapjoy dashboard. To do this, click the icon at the top right of the dashboard and select "+ Add App" from the drop down menu.
Once your application has been set up on the Dashboard, you can begin to integrate the SDK in your code. This document explains how to integrate the Tapjoy SDK into a new iOS app.
The first step in integrating with your app is to download the SDK itself. You can do so from here.
After unzipping the SDK, you should see the following folders and files:
(The “TapjoyEasyApp” folder contains sample projects that demonstrate the Tapjoy integration. You do not need it for integrating Tapjoy into your own application.)
To add the files to your project, right click the project icon in your project explorer in Xcode, then select Add Files to "Your App"… A dialogue will appear. Navigate to and select the Tapjoy.embeddedframework folder in the Libraries folder of the SDK .Make sure your dialogue looks like the following:
Click the Add button.
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.
Add all of the following frameworks to your project:
- CoreTelephony (Can be marked Optional for compatibility with older iOS’s)
- ImageIO.framework (SDK 11.10 and higher)
- StoreKit (Can be marked Optional for compatibility with older iOS’s)
Note that if you are also publishing with Tapjoy (i.e. using it for analytics or to show ads or messages) you will have to add more frameworks. Please see the Getting Started Guide iOS for Publishers.
- add the following line to your Podfile: pod ‘TapjoySDK’
- Execute the following at the command line: ‘pod install’
At this point, it’s a good idea to compile and run your application to ensure that everything in your app is still working. Since we haven’t actually done anything to your application’s code, there should be no errors or changes in how your application functions. If there is a problem, see the FAQ for more information or contact support.
Now it’s time to actually write some Tapjoy code!
The first bit of code you will need is an import, so Tapjoy’s functionality becomes accessible to your application. Place the following import statement at the beginning of your application’s app delegate class file (usually called AppDelegate.m or YourAppNameAppDelegate.m):
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 in the top navigation bar:
The SDK Key is the long alphanumeric string at the bottom of this page:
Now, place the following snippet of code into the application didFinishLaunchingWithOptions: method in your application’s app delegate file:
//Turn on Tapjoy debug mode [Tapjoy setDebugEnabled:YES]; //Do not set this for any version of the game released to an app store! //The Tapjoy connect call [Tapjoy connect:@"Your-SDK-Key-iOS-from-the-dashboard-here"];
Be sure to actually paste your SDK Key into place where it says "Your-SDK-Key-iOS-from-the-dashboard-here".
Now compile and run your application. If you have done everything correctly, you should see output on the console log similar to the following:
2015-01-29 16:01:54.770 Storyteller Roller[25869:1433019] [TJLog level: 4] Tapjoy Request: https://connect.tapjoy.com/api/connect/v3?library_version=22.214.171.124&app_version=1.4&pkg_rev=1.4&language_code=en&display_h=920&debug=true&session_id=c6e10e7067a18bb425ef17f3007186df78d5b9bafd0ed395f704b4bf4b58ce08&display_d=326×tamp=1422576114&device_type=iPhone%20Simulator&ad_tracking_enabled=true&fq30=5&os_version=8.1&library_revision=595b80&timezone=America%2FLos_Angeles&plugin=native&display_w=640&advertising_id=255C116D-3A50-434A-8838-31B3C0F9A74C&installed=1422039583251&platform=iOS&verifier=c0fed4e49b6022021c76031b99e46bc5a814ea0668bfcc3b8310e263e848ffff&analytics_id=6FCA4732-3B30-4A8D-9D96-3554DDD4FFFF&connection_type=wifi&pkg_id=com.zdrake.storytellerdiceroller&display_multiplier=1.000000&country_code=US&sdk_type=event&lad=0&device_name=x86_64&fq7=5&bridge_version=1.0.6&install_id=8350D4E1-761D-40D0-9A42-1753711889EA-8398-00002F3FE1C38D8B&pkg_ver=1.4&app_id=ef744903-c16c-4dd6-bd6e-561ef35fffff&session_total_count=41&device_location=true&store_view=true 2015-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 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.
TROUBLESHOOTING TIP: Double check the app id and make sure there are no additional whitespace before or after the App ID.
Once you’ve confirmed that your app is integrated correctly, you can go ahead and submit your app to the iOS App Store. Once the version of your app with our SDK is live:
- Go to your app, and select "User Acquisition" on the top navigation bar.
- If you have not already done so, click the "Create Ad" button in the upper right to create your ad.
- Find the ad you want to run in the list at the bottom of the screen.
- Click the "Not Approved" status indicator and select “Submit Approval Request” from the drop-down.
- Tapjoy Support Team will verify your integration with the latest build on the market, and will let you know when your app is Tapjoy Enabled. After your app is Tapjoy enabled, you can make this campaign go live by clicking on the ON/OFF switch next to the campaign.