SDK

Explore Tapjoy’s iOS SDK reference to learn how to request placements, handle callbacks, display ad content, and integrate core SDK functions.

Read time 4 minutes

Last updated 3 hours ago

Requesting a Placement

First, import

TJPlacement.h

at the top of the file.


#import <Tapjoy/TJPlacement.h>


// Import already happens automatically through your bridging header

Then create an instance of the TJPlacement class and initialize it with your placement name. Be sure the placement name string in your code exactly matches the placement name in the dashboard. You can also implement a delegate to receive callbacks (explained below).


TJPlacement *p = [TJPlacement placementWithName:@"Main Menu" delegate:self];


let p = TJPlacement(name: "Main Menu", delegate: self)

Finally, request the content.


[p requestContent];


p?.requestContent()

Before you request content, ensure that the Tapjoy connect call has succeeded. Do not make a request before you have observed the TJC_CONNECT_SUCCESS notification.

Pre-caching the content

For the best user experience, 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.

TJPlacement Callbacks

To get feedback on the status of the content request, implement the following TJPlacementDelegate methods:


- (void)requestDidSucceed:(TJPlacement*)placement{}  // Called when the content request returns from the Offerwall servers. Does not necessarily mean that content is available.
- (void)requestDidFail:(TJPlacement*)placement error:(NSError*)error{}
- (void)contentIsReady:(TJPlacement*)placement{} //This is called when the content is actually available to display.
- (void)contentDidAppear:(TJPlacement*)placement{} 
- (void)contentDidDisappear:(TJPlacement*)placement{}


func requestDidSucceed(_ placement: TJPlacement!) {} // Called when the content request returns from the Offerwall servers. Does not necessarily mean that content is available.
func requestDidFail(_ placement: TJPlacement!, error: Error!) {}
func contentIsReady(_ placement: TJPlacement!) {} //This is called when the content is actually available to display.
func contentDidAppear(_ placement: TJPlacement!) {}
func contentDidDisappear(_ placement: TJPlacement!) {}

Displaying a Placement

To actually display content, call show:


[p showContentWithViewController: nil];


p.showContent(with: nil)

If you pass ‘nil’ to

showContentWithViewController

, the Offerwall SDK will create it’s own view controller to handle display of the ad. In most cases, this is the safest option. If you have a complex view hierarchy and for some reason want to mange the display yourself, you can optionally pass a view controller of your own to

showContentWithViewController

. It is vitally important that the ViewController passed to this method be the top-most view and that it be unobstructed by other views, and that other views are not placed on top of this view until after the Tapjoy content has been dismissed. Check to make sure that content is ready before calling show:


if (p.isContentReady) {
   [p showContentWithViewController: nil];
}
else {
  //handle situation where there is no content to show, or it has not yet downloaded.
}


if (p.isContentReady) {
    p.showContent(with: nil)
} else {
  //handle situation where there is no content to show, or it has not yet downloaded.
}

The recommended best practice is to mute your app’s 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 contentIsReady 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.

Re-requesting the content

When you successfully display content from a placement to a user, you must request content again (for example, call

[p requestContent];

again) to "reload" the placement with another content unit. You cannot call

[p showContentWithViewController: self];

again. If you try to show content before requesting content, the show content will fail.

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 TJActionRequestDelegate methods are called and passed the appropriate information from the content unit:


- (void)placement:(TJPlacement*)placement didRequestPurchase:(TJActionRequest*)request productId:(NSString*)productId {
        //called when user clicks the product link in IAP promotion content
        //implement code here to trigger IAP purchase flow for item  here
}
- (void)placement:(TJPlacement*)placement didRequestReward:(TJActionRequest*)request itemId:(NSString*)itemId quantity:(int)quantity {
        //called when the reward content is closed by the user
        //implement code here to give the player copies of item 
}


func placement(_ placement: TJPlacement!, didRequestPurchase request: TJActionRequest!, productId: String!) {
    //called when user clicks the product link in IAP promotion content
    //implement code here to trigger IAP purchase flow for item  here
}

func placement(_ placement: TJPlacement!, didRequestReward request: TJActionRequest!, itemId: String!, quantity: Int32) {
    //called when the reward content is closed by the user
    //implement code here to give the player copies of item
}

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:


TJEntryPointUnknown //Not set, but removes any value that was already set
TJEntryPointOther
TJEntryPointMainMenu
TJEntryPointHud
TJEntryPointExit
TJEntryPointFail
TJEntryPointComplete
TJEntryPointInbox 
TJEntryPointInitialisation
TJEntryPointStore


TJEntryPoint.unknown
TJEntryPoint.other
TJEntryPoint.mainMenu
TJEntryPoint.hud
TJEntryPoint.exit
TJEntryPoint.fail
TJEntryPoint.complete
TJEntryPoint.inbox
TJEntryPoint.initialisation
TJEntryPoint.store

Set the entry point after creating your placement object, but before requesting content:


TJPlacement *placement = [TJPlacement placementWithName:@"myPlacement" delegate:nil];
[placement setEntryPoint:TJEntryPointMainMenu];
[placement requestContent];


let placement = TJPlacement(name: "myPlacement", delegate: nil)
placement?.entryPoint = TJEntryPoint.mainMenu
placement?.requestContent()

Documentation

Engine

Services

Grow

Industry

Support

Tapjoy Offerwall

Get started with Unity LevelPlay

Get started with Unity Ads User Acquisition

Get started with Unity Ads Monetization