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

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

The Tapjoy Unity Plugin zip contains a Unity package file for easy importing, and the raw files for those who prefer to drag-n-drop files for their Tapjoy upgrade. To import the TapjoyUnityPlugin_vVERSION.unitypackage:

  1. Open your Unity project
  2. Assets > Import Package > Custom Package
  3. Point to the TapjoyUnityPlugin_vVERSION.unitypackage file
  4. Review the list of import files checking for any conflicts
  5. Press the "Import" button to accept the files

Starting with 12.8.0 the Tapjoy SDK is now managed via Cocoapods by the External Dependency Manager. Please ensure your Cocoapods version is 1.9.0 or greater and your Xcode version is 11.0 or greater

A. Updating on Unity 5.4 or higher:

If you are updating your integration and you are using Unity 5.4 or higher, you will see a "fix" button that allows you to correct an error involving the Google Play Services library being marked for inclusion in iOS builds.

Please click the "Fix" button to make sure Google Play Services is only included in Android builds. For versions of Unity earlier than 5.4, you will have to manually ensure that google-play-services_lib is set to be included only with Android builds. Note that n****ew integrations do not need this fix and will not see this button.

B. Add App Permissions (for Android)

The ACCESS_WIFI_STATE permission can optionally be included in your manifest:

<manifest ...>
  ...
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
  ...
</manifest>

3. Connect to Tapjoy

You can start configuing Tapjoy in the Tapjoy Window. Go to Window > Tapjoy to open Tapjoy Window.

image_title

In Tapjoy Window, you can configure following:

  • Set the SDK Key for Android and iOS
  • Add the Store name for android market(Google, Amazon, and etc.)
  • Enabling or disabling use of Advertising ID, Persistent ID, and IDFA
    • Disable Advertising Id: This checkbox has the same effect as the DISABLE_ADVERTISING_ID_CHECK connect flag in Android. 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 checking this box, 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.
    • Disable Persistent Ids: This checkbox has the same effect as the DISABLE_PERSISTENT_IDS connect flag in Android. Tapjoy SDK sends persistent identifiers (such as MAC address and Android Identifier) to Tapjoy servers to be used as fallback advertising identifier for the cases where advertising identifiers are not available (an option suggested in the Android Developer Documentation here (Section: Targeting devices without an advertising ID)). If this flag is set, persistent identifiers are sent to Tapjoy servers for advertiser tracking purposes only if the Advertising Identifier is unavailable within the SDK.
    • There is no checkbox equivalent to the DISABLE_ANDROID_ID_AS_ANALYTICS_ID connect flag. (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.) If you wish to set this flag, you will have to use the Tapjoy Unity manual connect and add the DISABLE_ANDROID_ID_AS_ANALYTICS_ID flag.
  • Enabling or disabling debug mode (including console logging). Be sure this is disabled for all release builds.

You also can check the status of your integration, including GCMReceiver Setting and Install Referrer Receiver Setting.

For the Tapjoy SDK to work it requires a TapjoyUnity GameObject with an attached TapjoyComponent – in the editor window there will be a "Fix" button that will automatically add and set up this GameObject for you. Add the Tapjoy GameObject only to the first scene that appears first in your game.

Once you have finished configuing Tapjoy you can build 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.

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(TJSegment.VIP);
Tapjoy.SetUserSegment(TJSegment.Payer);
Tapjoy.SetUserSegment(TJSegment.NonPayer);
Tapjoy.SetUserSegment(TJSegment.Unknown); 

A. Manual Connect

The Unity SDK allows you to control your connection step through code. By default the SDK will handle connection for you. To gain manual control, first uncheck the "Auto-Connect" option in the Tapjoy Settings Window (Window > Tapjoy).

Once that option is unchecked the SDK will no longer automatically handle the connection for you. You will need to handle the connection with your code, this behavior is just like in the Native SDKs.

When your application first starts up, you must call Connect to make the SDK connect to the Tapjoy server. There are two versions of the Connect function. The first form of Connect will just take the SDK key as a string. If your application is multi-platform you will need to provide the correct SDK key for each platform.

#if UNITY_ANDROID
		Tapjoy.Connect("your_android_sdk_key");
#elif UNITY_IOS
		Tapjoy.Connect("your_ios_sdk_key");
#endif

The other version of Connect takes a second parameter, a Dictionary of string/string values. This dictionary is your connectFlags, and they behave the same as in the Native SDKs.

Dictionary<string,string> connectFlags = new Dictionary<string,string>();
connectFlags.Add("TJC_OPTION_USER_ID", "<USER_ID_HERE>");

#if UNITY_ANDROID
  Tapjoy.Connect("your_android_sdk_key", connectFlags);
#elif UNITY_IOS
  Tapjoy.Connect("your_ios_sdk_key", connectFlags);
#endif

Before you can perform other actions with the SDK (such as loading ads), the SDK connection must complete. There are two event delegates that are triggered by connection events – OnConnectSuccess and OnConnectFailure. You should declare delegate functions to listen for the connection events. Once onConnectSuccess has fired you can begin using the other SDK functions.

Should the SDK fail to connect, you can re-attempt the Connection by calling Connect() with no parameters. This will make the SDK re-try it’s connection using the SDK key that it last attempted to connect with.

B. Callbacks

Now that you have the SDK running, it’s time to take a moment to code for best practices. Before the Tapjoy SDK can request ads or send tracking data, it needs to successfully connect to our servers. The SDK exposes a delegate function OnConnectSuccess that will fire once the SDK has successfully connected. You should wait until the SDK has successfully connected before you attempt to use other functions such as requesting ads or tracking data. The OnConnectWarning callback will fire when there is a non-blocking issue during connect (connectSuccess will also fire after). Currently this feature will only detect issues with UserId when sent in ConnectFlags. OnConnectFailure indicates and error has occurred and the SDK did not connect.

Tapjoy.OnConnectSuccess += HandleConnectSuccess;
...

public void HandleConnectSuccess() {
    Debug.Log ("Connect Success");

    // Now that we are connected we can start preloading our placements
    TJPlacement p = TJPlacement.CreatePlacement("my_placement");
    p.RequestContent();
}

Tapjoy.OnConnectWarning += HandleConnectWarning;
...

void HandleConnectWarning(int code, string message)
{
    
}

Tapjoy.OnConnectFailed += HandleConnectFailed
...

public void HandleConnectFailed(int code, string message){

}

You can also check the boolean Tapjoy.isConnected to check SDK connection status.