Table of Contents
- 1 Summary
- 2 Setup Instructions
- 3 Multiple Tapjoy instances in Mopub mediation
- 4 Tapjoy Rewards in MoPub
- 5 Sample code
[Alert May 2016]: Note from Google: If you are using a Mopub SDK version before 4.4.0, you should update right away to address a security issue. After July 16, 2016, Google will start rejecting apps that include Mopub versions earlier than 4.4.0. For more information, see Google’s FAQ answer about Mopub.
This guide will cover how to integrate Tapjoy as an ad network through MoPub mediation for running rewarded videos, using Tapjoy 11.x (current and recommended).
Overview of Mopub Adapter mediation
In this configuration, your application talks to the Mopub SDK, which in turn requests content from the Tapjoy SDK. Reward information is passed directly from Tapjoy’s SDK to your application, or from Tapjoy’s server to your server (see the section on Rewards below). Here is a diagram showing the flow of information in a Tapjoy -Mopub adapter mediation:
Using Tapjoy Functionality with Mopub-Tapjoy Adapter Integration
Many publishers wish to use Tapjoy functionality (OfferWall, IAP Promotion, Analytics, etc.) along with using Tapjoy as an ad provider for a Mopub Adapter Mediation. Since part of the Mopub Adapter Mediation includes an integration of the Tapjoy SDK, all Tapjoy functionality is available to your application without any additional integration steps.
- Tapjoy SDK 11.0.3 or above: Download
- MoPub SDK (this adapter was tested with MoPub 4.0): Download
- Tapjoy Custom Event code: iOS, Android, Unity
Before You Start, Make Sure:
- Your app is registered in your MoPub account and has the MoPub SDK integrated
- Your app has configured the Rewarded Ad Unit on MoPub and has included the Tapjoy custom event code
- You have read through MoPub Getting Started guides for Android and iOS, or Unity
- You have a Tapjoy dashboard account and SDK key for the app you want to run ads
- You have set up Tapjoy "Video" content card via the Placements framework on the Tapjoy Dashboard. You must set up a User Initiated Placement and connect a "Video" content card to that placement. Please see the links below for more details:
Integrating Tapjoy into your iOS, Android, or Unity App
- Follow the instructions to integrate the Tapjoy embedded framework and make the connect call to initialize Tapjoy. Make sure to call ‘connect’ to start the Tapjoy SDK.: https://dev.tapjoy.com/ sdk-integration/ios/getting-started-guide-publishers-ios/
- Integrate the pre-built Tapjoy-MoPub Rewarded Video adapter for iOS (available on MoPub GitHub)
- Follow the instructions to integrate the Tapjoy jar and make the connect call to initialize Tapjoy: https://dev.tapjoy.com/sdk-integration/android/getting-started-guide-publishers-android/
- Integrate the pre-built Tapjoy-MoPub Rewarded Video adapter for Android (available on MoPub GitHub)
- Integrate the Tapjoy SDK: dev.tapjoy.com/sdk-integration/unity/getting-started-guide-publishers-unity/
- Integrate the MoPub Unity SDK: https://github.com/mopub/mopub-unity-sdk/
- Integrate the Tapjoy-MoPub Rewarded Video Adapters. We have a unitypackage that contains the adapter files here for your convenience. You can download the unitypackage for the adapter files on Tapjoy’s bintray here: https://bintray.com/tapjoy/mediation-unity/mopub
Tapjoy Network Setup in MoPub
Follow the instructions here explain how to add a Custom Native Network to your Mopub setup. You must do this for Tapjoy. For your convenience, we have included instructions specific for Tapjoy here:
- In the Mopub Dashboard, go to the Networks tab, and click "Add a Network”.
- Select "Custom Native Network":
- Give it the title of "Tapjoy".
- For each Ad Unit, configure the ‘Custom Event Class’ and ‘Custom Event Class Data’ columns:
For running rewarded video ads, in the ‘Custom Event Class’ column enter:
TapjoyRewardedVideoCustomEvent for iOS
com.mopub.mobileads.TapjoyRewardedVideo for Android.
For running interstitial ads, in the ‘Custom Event Class’ column enter:
TapjoyInterstitialCustomEvent for iOS
com.mopub.mobileads.TapjoyInterstitial for Android
- In the “Custom Event Class Data” column, define a JSON object with the placement name as defined by your Tapjoy placement.For example, if the Tapjoy placement name is "level_complete" the JSON would be:
You’re finished! Be sure to test your Mobpub – Tapjoy mediation implementation to be sure everything is functioning correctly before you release your application to the app store.
Multiple Tapjoy instances in Mopub mediation
Sometimes, a publisher will want to set up more than one instance of Tapjoy in a single Mopub mediation waterfall. Usually this is so you can have Tapjoy instances with different eCPM targets. For example, you might have one Tapjoy rewarded video instance with high eCPM target, one with a mid-level eCPM target, and one with a low eCPM target. This can lead to a substantial increase in revenue over having a single instance, because you will be able to capture high-value Tapjoy ads at the top of the waterfall, without losing access to a "backfill" of lower-value ads further down in the waterfall. Typically, a publisher will set up two or three such instances.
Note that in order to set eCPM target, you have to speak to your Tapjoy Account Manager. It is not something you can do yourself from the Tapjoy dashboard.
Setting up multiple Tapjoy instances in Mopub
To set up multiple Tapjoy instances on Mobpub, you configure each instance as a separate Custom Native Network in Mopub’s dashboard. In effect, Mopub will treat each Tapjoy instance as a completely separate ad network. This will allow you to have multiple copies of Tapjoy within the same mediation waterfall.
- Integrate the Mopub and Tapjoy SDKs into your application as you would for a normal, single-instance integration.
- Go to your application in the Tapjoy dashboard. (Or create it, if you have not already done so.)
- For each Tapjoy instance you want to create, create a placement and give it an appropriate name (e.g. "TapjoyVideo-low", "TapjoyVideo-middle", "TapjoyVideo-high"):
- Create a separate content card for each placement. This will be a Video or Interstitial card, depending on the type of mediation waterfall you are setting up. Do not use the same content card for all the placements: if you do this, you will not be able to create separate eCPM targets for each placement, as those targets are set at the content card level, not the placement level.
- Give each card an appropriate name (e.g. "High eCPM video", "Mid eCPM video", "Low eCPM video"). To avoid confusion, we recommend giving the content card a name different than the placement it will be attached to.
- Attach the content card to the appropriate placement. Make sure that the content card is attached to the correct placement: the "High eCPM video" card should be in the"TapjoyVideo-high" placement, etc. When you are finished, your Tapjoy placements should look similar to this:
- Contact your Tapjoy Account Manager, and have them set an appropriate eCPM target for each content card. This can only be set from the Tapjoy side. Provide the exact name and platform of your application, and the exact names of the content cards that need to have an eCPM target set.
- Set up one Custom Native Network on the Mopub dashboard for each Tapjoy instance you will have in your waterfall. See "Tapjoy Network Setup in Mopub", above.
- Instead of calling the network "Tapjoy", call it something like "Tapjoy-High eCPM" so it’s clear which instance it is.
- When entering the placement name in step 5 of the "Tapjoy Network Setup in Mopub", be sure to use the correct Tapjoy placement name that you set up on the Tapjoy dashboard. It is important to use the placement name, not the content card name. For example, if you are creating the "Tapjoy-High eCPM" network, be sure that the JSON object in the “Custom Event Class Data” column points to the high-eCPM Tapjoy placement, e.g.:
- If you are using multiple instances in both video mediation and interstitial mediation, you can use the same Custom Native Network for one interstitial instance and one video instance. So you could create a single "Tapjoy-High eCPM" network, rather than creating separate "Tapjoy-High eCPM video" and "Tapjoy-High eCPM interstitial" networks.
- Make sure the networks you created in the previous step are enabled and running. You might have to click on the "Segments" tab in the top Mopub menu bar and enable the networks. The Tapjoy networks should be "Running" with a blue check mark next to them:
- You’re finished! Be sure to test your Mobpub – Tapjoy mediation implementation to be sure everything is functioning correctly before you release your application to the app store.
Tapjoy Rewards in MoPub
Tapjoy provides the ability for Publishers to manage currency rewards depending on how/where the currency balance is maintained:
- Self-Managed Currency: Publishers that are managing the currency balances on their own will need to provide a post-back URL to Tapjoy. The post-back URL will receive the reward amount upon successful completions of ad actions (i.e. watching a video): https://dev.tapjoy.com/virtual-currency/non-managed-currency/
- Tapjoy Managed Currency: Tapjoy has a free service that publishers can use to hold the user stored value accounts for their virtual currencies. The service provides a ledger for holding the currencies earned (or purchased) by the users. For publishers that are using this service, Tapjoy manages and updates the currency rewards based on the completion of ad actions. More details on how to use the service and how to update balances can be found here: https://dev.tapjoy.com/virtual-currency/managed-currency/
Please note that in the current implementation, Tapjoy does not pass the reward amount to the MoPub framework, this means publishers will not get the reward amount in the reward callback as provided by the MoPub framework. Instead, the currency reward will be handled by Tapjoy (outside of the MoPub adapter) depending on the type of currency (Tapjoy managed vs. self-managed as described above) used in the application.
This sample code shows how to interface between MoPub’s rewarded video callbacks and Tapjoy’s Virtual Currency system ( for ‘managed currency’ only):