ENGSDK
1. Requesting a Placement
To request a Placement, use the TJPlacement class. Be sure the Placement name string in your code matches the Placement name in the dashboard exactly:
// Set current activity. If you are using Tapjoy session tracking or supported minSdkVersion>14,
// this can be skipped.
Tapjoy.setActivity(activity);
TJPlacementListener placementListener = this;
TJPlacement p = Tapjoy.getPlacement("[PLACEMENT_NAME]", placementListener);
Once the listener methods are in place, and the placement has been instantiated, you can request content for that placement:
if(Tapjoy.isConnected())
p.requestContent();
else
Log.d("MyApp", "Tapjoy SDK must finish connecting before requesting content.")
NB: Before you request content please ensure that the Tapjoy connect call has succeeded. Do not make a request before you have received the onConnectSuccess callback.
2. Pre-caching the content
For the best user experience, you should request content in advance of when the user might be shown that content. For example, if the placement is a button on your main menu, you might want to request content for it when your application starts, just after the Tapjoy Connect call succeeds. If you wait until the last moment to request content, it is likely the user will have to wait for the content to load, and watch a loading spinner. For ads, this makes the user less likely to interact with the ad, and therefore less likely to make money for you.
3. Listeners
You will need to prepare delegate methods to handle the various placement responses. At a minimum your class will need to extend the TJPlacementListener interface (public class YourMainActivity extends and Activity implements TJPlacementListener). The Tapjoy EasyApp sample app has a complete code example showing how this can be done. The primary methods defined by the TJPlacementListener interface are:
public void onRequestSuccess(TJPlacement placement); // This just means the SDK has made contact with Tapjoy's servers. It does not necessarily mean that any content is available.
public void onRequestFailure(TJPlacement placement, TJError error);
public void onContentReady(TJPlacement placement); //This is called when the content is actually available to display.
public void onContentShow(TJPlacement placement);
public void onContentDismiss(TJPlacement placement);
Note that you should mute your audio before showing content from a placement that might include video, otherwise the audio for the video and your app’s audio might conflict.
Often, it is a good idea to wait until the onContentReady delegate fires before showing content to the user. This way, you can be sure that the content is actually on the device, and can be shown to the user without delay. Another equivalent way is to check to see if p.isContentReady() is true, as in the example above.
NOTE: In order to ensure proper functionality, prior to creating a placement object, the Tapjoy connect call needs to have been made and succeeded.
4. Show a Placement
When you request a TJPLacement you pass along a TJPLacementListener object. Your TJPlacementListener has a callback for "onRequestSuccess". The onRequestSuccess callback is fired after the SDK has successfully made a content request to our servers. Once this fires, you can check if the TJPlacement has content by calling the isContentAvailable function:
public void onRequestSuccess(TJPlacement tjPlacement)
{
if(tjPlacement.isContentAvailable())
{
//There is an ad unit available
}
else
{
//Fall-through
}
}
Please note that isContentAvailable means that there is an ad available, but that does not mean it has finished downloading. Once the ad finishes loading it will fire off the TJPlacementListener’s onContentReady function. You can also call isContentReady on the TJPlacement object to check if it has finished loading. You can display the ad any time after it has finished loading by calling its showContent function.
public void onContentReady(TJPlacement tjPlacement)
{
if(tjPlacement.isContentReady())
{
// We can uncomment the following line to show the ad as soon as it finishes loading,
// or call showContent at a later point once we're ready to display the ad.
tjPlacement.showContent();
}
}
5. Re-requesting the content
Once you successfully display content from a placement to a user, you must request content again (i.e. call p.requestContent(); again) to "reload" the placement with another content unit. You cannot simply call p.showContent(); again. If you try to show content before requesting content, the show content will fail.
You can show content if content is ready:
if(p.isContentReady()) {
p.showContent();
}
else {
//handle situation where there is no content to show, or it has not yet downloaded.
}
6. Handling Tapjoy Content Action Requests
Some Tapjoy content types, like Reward and IAP Promotion, require your code to take action based on parameters passed by that content unit. For example, the Reward content unit specifies an item name (a string) and a quantity (an integer) to be given to the user. It is up to the application to actually adjust the user’s inventory to reflect the reward. The following delegate methods exist for these special types of content unit:
public void onPurchaseRequest(TJPlacement placement, TJActionRequest request, String productId); //onPurchaseRequest called when user clicks the product link in IAP promotion content. Put the code that actually triggers the IAP here.
//
//
public void onRewardRequest(TJPlacement placement, TJActionRequest request, String itemId, int quantity); //called when the content closed in reward content
Note that onRewardRequest is NOT what gets called when Tapjoy rewards the user for interacting with an ad. It is only used for the Reward content unit.
To learn how to use these special content units please check the following documentation pages. Reward Giveaway Content Units. "In App Promotion" Content Units.
7. Setting the Entry Point
You can optionally tell Tapjoy the 'entry point' of each placement. There are a variety of preset values to choose from:
TJEntryPoint.ENTRY_POINT_UNKNOWN
TJEntryPoint.ENTRY_POINT_OTHER
TJEntryPoint.ENTRY_POINT_MAIN_MENU
TJEntryPoint.ENTRY_POINT_HUD
TJEntryPoint.ENTRY_POINT_EXIT
TJEntryPoint.ENTRY_POINT_FAIL
TJEntryPoint.ENTRY_POINT_COMPLETE
TJEntryPoint.ENTRY_POINT_INBOX
TJEntryPoint.ENTRY_POINT_INIT
TJEntryPoint.ENTRY_POINT_STORE
You should set the entry point after creating your placement object, but before requesting content:
TJPlacement placement = Tapjoy.getPlacement("myPlacement", null);
placement.setEntryPoint(TJEntryPoint.ENTRY_POINT_MAIN_MENU);
placement.requestContent();