Quickstart

1. Dashboard Integration Guide

The Tapjoy Dashboard has a built-in Integration Guide that will walk you through the steps of a Tapjoy integration. You can use this Getting Started Guide document as a reference if you prefer or you can go directly to the Integration Guide for your most recent app.

2. SDK Integration

A. Maven (recommended)

Maven allows you to integrate Tapjoy by adding a few lines to your applications build.gradle file. To use Tapjoy simply add it to your build.gradle file:

    repositories {
      maven {
        name "Tapjoy's maven repo"
        url "https://sdk.tapjoy.com/"
      }
      maven {
        name 'Google'
        url 'https://maven.google.com/'
      }

    }

    dependencies {
      implementation 'com.tapjoy:tapjoy-android-sdk:13.2.1'
    }

B. Add App Permissions and Activities

The following permissions are needed:

  • ACCESS_WIFI_STATE(optional)

You will also need to add the same configChanges to your App’s Manifest activity:

  android:configChanges="orientation|keyboardHidden|screenSize"

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.

AD_ID and the Google Play Families Progam

Tapjoy 12.9.0 includes play-services-ads v17.1.0. This version of play-services-ads includes the AD_ID permission which must be removed for members of the Google Play Families Program.

You can exclude the permission by adding the following element to your manifest:

  <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>

More details are available 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 it's time to write some code. Import Tapjoy in to your Activity:

java
  import com.tapjoy.Tapjoy

Then in your main Activity's onCreate() method connect to Tapjoy:

java
  Hashtable<String, Object> connectFlags = new Hashtable<String, Object>();
  connectFlags.put(TapjoyConnectFlag.ENABLE_LOGGING, "true"); // Disable this in production builds
  connectFlags.put(TapjoyConnectFlag.USER_ID, "USER_ID_GOES_HERE"); // Important for self-managed currency

Tapjoy.connect(getContext().getApplicationContext(), "SDK_KEY_GOES_HERE", connectFlags, new TJConnectListener() {
    @Override
    public void onConnectSuccess() {
        
    }
    @Override
    public void onConnectWarning(int code, String message) {
        
    }
    @Override
    public void onConnectFailure(int code, String message) {
        
    }    
}); 

In this code you can see that we connect to Tapjoy (listening for the success, failure, and warning callbacks) and we configure two 'connect flags' (logging and user id). onConnectSuccess indicates the SDK has successfully connected to the Tapjoy servers. If we connect successfully but there is a non-blocking issue onConnectWarning will fire first. Currently this feature will only detect issues with UserId when sent in ConnectFlags. If we cannot connect to the servers successfully, onConnectFailure will fire.

The two most common and useful connect flags for Publishers are ENABLE_LOGGING and USER_ID.

You will use the logging flag in your debug builds but it is important to disable when you are building for production.

Setting the USER_ID flag is crucial when you are using a self-managed currency. Setting it at connect is important as it ensures it is set before any placement is called, preventing potential rewarding issues.

Some other connect flags that are useful to help publishers control how Tapjoy uses the various Android Identifiers supplied by the operating system:

  • ALLOW_LEGACY_ID_FALLBACK (available in SDK versions 12.2.1 and later) If this flag is set, the Tapjoy SDK will use persistent IDs for advertising purposes if the advertising ID is not available.
  • DISABLE_ANDROID_ID_AS_ANALYTICS_ID [Deprecated in SDK version 13.3.0] If this flag is set, the ID that Tapjoy uses for analytics purposes is not a copy of the Android ID, but instead a randomly generated string of characters. Releasing a build that changes the setting of this flag from the previous version may result in some of your existing users being seen as new users by Tapjoy’s analytics tools.
  • DISABLE_ADVERTISING_ID_CHECK By default, Tapjoy’s Android SDK checks for the existence of the Google Advertising Identifier and will fail to initialize if it does not find it. By setting this flag, you can disable this check so that the Tapjoy SDK initializes even if there is no Google Advertising Identifier present. This is useful when Google Play Services is not present in the app, such as when you are making a build for release in a non-Google Play app store.

For an explanation of all connect flags, Please see the Java SDK Reference.

Now compile and run your application.

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.

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

java
Tapjoy.setUserSegment(TJSegment.VIP);
Tapjoy.setUserSegment(TJSegment.PAYER);
Tapjoy.setUserSegment(TJSegment.NON_PAYER);
Tapjoy.setUserSegment(TJSegment.UNKNOWN);