Tapjoy Integration Guide

This guide will instruct you step-by-step on how to set Tapjoy live as an Ad Network on Unity LevelPlay.

Step 1. Create an Tapjoy Account

1. 1. Create an account with Tapjoy. You can do so here.

1. Click on the link in the confirmation email to verify your account. Once your account has been verified, you can log in to their partner login here.

Step 2. Create an Application in Tapjoy

To gain access to Tapjoy’s inventory through Unity LevelPlay, you must first add your app and set up Ad Zones in your Tapjoy account.

1. Add Your App

   1. Log into your Tapjoy account.
      1. If you are a new user on Tapjoy you will be presented with this window, and can simply select ‘Create App‘:
         
      2. If you are a registered user, add an app by clicking on the top-right corner and select ‘+Add App‘:
         

   2. Define App Settings

      1. Platform – iOS or Android or both
         
         Note:  While Tapjoy allows you to create your app with both platforms, you will need a unique Tapjoy SDK Key per platform (iOS + Android) to enable it in your ironSource account. If you use a combined Dashboard on Tapjoy it will give you both an iOS and Android SDK key.
         
      2. App Name
      3. Orientation 
      4. Time Zone
      5. Currency
      6. Select ‘Create Now’ to finish.
         

Step 3. Add Placement, Virtual Currency and Content

1. Ad Placement

   Once your application has been added, Tapjoy will create default placements for you. Placements are the ad zones to which Tapjoy delivers ads. This will thus be the placement in your app where Tapjoy’s Video or Interstitial will be triggered through Unity LevelPlay.
   Important! Placements must be user-initiated to work in conjunction with Unity LevelPlay.

   Go to the Monetization tab in the top menu and in the left side bar select ‘Placements‘.
   Click on the settings icon on one of the default placements:

   1. If you are using the auto created placements, you can rename the placement if you wish. Note that the placement name must later be inserted on the ironSource platform. If you are serving both Tapjoy’s Video and Interstitial, you will need two separate placements, one for Rewarded Video and another for Interstitial.
      
   2. If you decide to create a new placement to work in conjunction with Unity LevelPlay platform, select ‘Create Placement’ on the right-hand side.
      
   3. Enter the name and description for this placement and Click ‘Create‘.
      

2. Virtual Currency

   Next, you need to add a virtual currency to your Tapjoy account. All content units on Tapjoy must be associated with a virtual currency. Learn more on creating a Tapjoy Virtual currency on the Tapjoy Knowledge Center.

   1. In the Monetization tab, navigate to the Virtual Currency section.
      
   2. Select the ‘Create Virtual Currency’ button on the top right.
      
   3. The below window will appear. Tapjoys recommends the Tapjoy Managed currency but if you choose to use the Self Managed option, we recommend inserting “NO_CALLBACK” in the “Callback URL or NO_CALLBACK” field, as this will avoid unnecessary currency calls as the ironSource SDK handles the rewarding for ads served through our mediation.
      1. Fill in the relevant details:
         1. Platform: iOS or Android
         2. Currency Name, e.g. coins, gold, chips, etc.
         3. Currency Usage Description
         4. Default Exchange Rate
         5. Callback URL or No_Callback (Self Managed currency only)
            We recommend inserting NO_CALLBACK 
         6. Initial Balance, the currency amount your user is given when s/he starts using your app.
         7. In-app virtual currency exchange to real world resources: no
            You can disregard the other steps as they are not required fields; leave them as is.
            
   4. Click ‘Create Now‘ and you will see your defined virtual currency as Enabled on your Virtual Currency dashboard.
      

3. Content Unit

   Lastly, you must add the relevant content card to the placement. Unity LevePlay platform supports both Rewarded Video and Interstitial content for Tapjoy.

   1. To add content to your placements, go to ‘Monetization‘ on the top menu bar. Navigate to ‘Create Content‘ on the left sidebar. You will then see the list of Tapjoy’s Monetization products. 
      
   2. Next, select the relevant ad unit you want to serve through Unity LevelPlay platform.
      1. To serve Rewarded Video, select Rewarded Video by clicking ‘Create‘.
         
         
      2. To serve Interstitial, select Interstitial by clicking ‘Create‘.
         
   3. Next, fill out the following form:
      1. Content Name & Description
      2. Platform– if your app supports both platforms, create two separate content units for each platform.
         
      3. Targeting– leave this section as is.
      4. Placement– select the relevant placement created to run in conjunction with Unity LevelPlay.
         
      5. Schedule & Frequency– leave this section as is.
      6. Virtual Currency– select the virtual currency created in the former step.
         
         Note:  Tapjoy Content Units must be associated with a virtual currency, even if you are using ironSource rewards to reward your users. Learn more on creating a Tapjoy Virtual currency on the Tapjoy Knowledge Center.
      7. Reward Options
         When serving Tapjoy’s Rewarded Video or Interstitials through Unity LevelPlay, you should set the Tapjoy reward to zero and hide the reward message.
         1. For Rewarded Video, this will ensure you don’t award the user twice and will prevent user confusion when seeing a Tapjoy generated message with a different reward amount.
         2. For Interstitial, Interstitials you serve through our Mediation are non-incentivized so you just need to ensure you configure these settings in Tapjoy’s dashboard.
            To do this simply set the Reward Type to Fixed Rewards, enter 0 for the Reward Amount and check the box to Hide Rewards:
            
      8. Click ‘Save‘.

Step 4. Activate Tapjoy on ironSource SDK Networks Module

There are a few pieces of data from your Tapjoy account which need to be inserted into your ironSource Network Setup Module in order for Tapjoy to work correctly in connection with ironSource:

Once you obtain this information, you must configure Tapjoy’s Parameters on Unity LevelPlay. By adding the above information correctly, you will be able to take full advantage of Tapjoy’s ad inventory and reporting data on Unity LevelPlay.

1. SDK Key

   Navigate to the ‘Settings‘ tab on the top menu and choose App Settings from the dropdown. On the App Info page, scroll down to the bottom of the page. Under Application Platforms, you’ll find the SDK Key for the app you want to run Tapjoy’s Video ads with on the Unity LevelPlay:

   

2. Reporting API Key

   On the same page as the SDK Key, simply navigate to the ‘Mediation Keys’ tab. There you will find a dedicated API Key for Supersonic (by ironSource):
   

3. Placement Name

   Under ‘Monetization‘, navigate to ‘Placements‘ ➣ User Initiated tab. There you will see the Placement Name.

   

Configure Tapjoy Parameters into ironSource Account

• Once you have all of these parameters, log in to your ironSource account and in the left sidebar, navigate to Monetize ➣ Setup ➣ SDK Networks. Then click Manage networks and you’ll see a list of all supported mediation networks.

• Select Tapjoy from the list of Available Ad Networks and click on ‘Activate‘, then ‘Save‘.  Tapjoy will then be enabled in the Available Ad Networks table.
  
• Make sure to select the app on which you’d like to run Unity LevelPlay with Tapjoy. Next, go to Tapjoy in the Setup list of Ad Networks and click on Setup.
  
• Insert the SDK Key and Placement Name for the relevant ad unit. Set status to Active and click ‘Save’.
  
• You will then see Tapjoy as Active for the defined app and ad unit on your Mediation Setup dashboard.
  
• Verify your integration with the Reporting API; this column will check your integration through the Reporting API and return three possible responses: Verified, Failed and No Response. Double check your integration and the information you entered above; then click ‘Retry‘ until you see ‘Verified’.

Step 5. Add the Tapjoy Adapter to Your Build

Unity Integration Manager  (Recommended)

Once you’ve completed SDK integration, you can download Tapjoy Adapter, using the Unity Integration Manager.

In your Unity Development platform, go to ironSource > Integration Manager.

If you already have the latest version of the adapters, the action button will be changed to “Updated”, and will be disabled.

Android (Manual Resolve)

To apply your changes, make sure you use the “Resolve” process. This will download all relevant artifacts, according to your choices. For detailed information see instructions here. 

Android Plugin Manual Integration

1. Download the Tapjoy android adapter:

   Download adapter from here.

2. Add the Tapjoy files to your Unity project:

   Import the file into Assets/Plugins/Android/.

iOS Plugin Manual Integration

1. Download the Tapjoy iOS adapter and SDK:

   Download the adapter and SDK from here.

2. Add the Tapjoy  adapter to your Unity project:

   Import adapter file into Assets/Plugins/iOS.

3. Add the SDK to your Xcode project:
   As Unity3D do not support XCFrameworks, please ad the SDK XCFrameworks directly to your Xcode project.

For Android Proguard Users Only

If you are using ProGuard with the TapJoy adapter, you must add the following code to your ProGuard file (Android Studio: proguard-rules.pro or Eclipse: proguard-project.txt):

#TapJoy
-keep class com.tapjoy.** { *; }
-keep class com.moat.** { *; }
-keepattributes JavascriptInterface
-keepattributes *Annotation*
-keep class * extends java.util.ListResourceBundle {
protected Object[][] getContents();
}
-keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable {
public static final *** NULL;
}
-keepnames @com.google.android.gms.common.annotation.KeepName class *
-keepclassmembernames class * {
@com.google.android.gms.common.annotation.KeepName *;
}
-keepnames class * implements android.os.Parcelable {
public static final ** CREATOR;
}
-keep class com.google.android.gms.ads.identifier.** { *; }
-dontwarn com.tapjoy.**

Step 6. Tapjoy Additional Settings

User-level below consent age

Unity LevelPlay lets publishers communicate Tapjoy’s belowConsentAge settings directly to the Tapjoy network. This feature is enabled using ironSource SDK 7.2.1+, Tapjoy Unity Adapter 4.1.24+.

Use the following syntax, to set Tapjoy belowConsentAge flag with the parameter True:

IronSource.Agent.setMetaData("tapjoy_coppa","true");

Use the following syntax, to set Tapjoy belowConsentAge flag with the parameter False:

IronSource.Agent.setMetaData("tapjoy_coppa","false");

Android Advertising ID Opt Out

Unity LevelPlay lets publishers communicate Tapjoy’s optOutAdvertisingID flag for apps targeting children to comply with the Google Families Program rules.
This feature is enabled using ironSource SDK 7.2.1+, and the Tapjoy Unity Adapter 4.1.25+.

Use the following syntax to set Tapjoy optOutAdvertisingID flag with the parameter True:

IronSource.Agent.setMetaData("Tapjoy_optOutAdvertisingID","true");

Use the following syntax to set Tapjoy optOutAdvertisingID flag with the parameter False:

IronSource.Agent.setMetaData("Tapjoy_optOutAdvertisingID","false");

You can read more about Tapjoy’s user privacy policy here.

Done!

You are now all set to deliver Tapjoy Ads within your application!