# SDK

> 参考基本 SDK 文档，了解如何使用 TJPlacement 类请求广告位，确保广告位名称与 Tapjoy 后台中配置的名称相匹配。

## 请求广告位##requesting-a-placement

要请求一个广告位，请使用 `TJPlacement` 类。确保代码中的广告位名称字符串与后台中的广告位名称完全匹配：

```java title="Java"
TJPlacementListener placementListener = this;
TJPlacement p = Tapjoy.getPlacement("[PLACEMENT_NAME]", placementListener);
```

监听器方法就绪且广告位已实例化后，即可请求该广告位的内容：

```java title="Java"
if(Tapjoy.isConnected())
	p.requestContent();
else
	Log.d("MyApp", "Tapjoy SDK must finish connecting before requesting content.")
```

在请求内容之前，请确保 Tapjoy connect 调用已成功。在收到 `onConnectSuccess` 回调之前，不要发起请求。

## 预缓存内容##pre-caching-the-content

为了提供最佳用户体验，请在向用户显示内容之前提前请求内容。例如，如果广告位是主菜单上的按钮，您可能需要在应用程序启动时（就在 Tapjoy Connect 调用成功后）为其请求内容。如果等到最后一刻才请求内容，用户很可能需要等待内容加载并看着加载图标旋转。对于广告，这种情况会导致用户不太可能与广告互动，因此不太可能给您带来收入。

## 监听器##listeners

您需要准备一些委托方法来处理各种广告位响应。您的类至少需要扩展 TJPlacementListener 接口 (public class YourMainActivity extends and Activity implements TJPlacementListener)。

`TJPlacementListener` 接口定义的主要方法如下：

```java title="Java"
public void onRequestSuccess(TJPlacement placement); // This just means the SDK has made contact with the Offerwall 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);
```

最好是在显示可能包含视频的广告位的内容之前先将音频静音，否则视频的音频与应用的音频可能会发生冲突。

通常，最好等到 onContentReady 委托触发之后再向用户显示内容。这样就可以确保内容已实际位于设备上，并可立即向用户显示而不会有延迟。另一种等效方法是检查 p.isContentReady() 是否为 true，如以上示例中所示。

> **Note:**
>
> 为了确保功能正常，在创建广告位对象之前，需要先发出 Tapjoy connect 调用并获得成功。

## 显示广告位##show-a-placement

请求 TJPLacement 时，您将传递一个 TJPLacementListener 对象。TJPlacementListener 具有“onRequestSuccess”的回调。onRequestSuccess 回调在 SDK 成功向我们的服务器发起内容请求后触发。触发后，可以通过调用 isContentAvailable 函数来检查 TJPlacement 是否有内容：

```java title="Java"
public void onRequestSuccess(TJPlacement tjPlacement)
{
	if(tjPlacement.isContentAvailable())
	{
		//There is an ad unit available
	}
	else 
	{
		//Fall-through
  }
}
```

> **Note:**
>
> `isContentAvailable` 表示有可用的广告，但这并不意味着该广告已完成下载。广告加载完成后，便会触发 TJPlacementListener 的 `onContentReady` 函数。您还可以在 TJPlacement 对象上调用 `isContentReady` 来检查是否已完成加载。在广告加载完成后的任何时间都可以通过调用 `showContent` 函数来展示广告。

```java title="Java"
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 when we're ready to display the ad.
	    tjPlacement.showContent();
	}
}
```

## 重新请求内容##re-requesting-the-content

成功向用户显示广告位中的内容后，必须再次请求内容（例如，再次调用 `p.requestContent();`），以便为该广告位“重新加载”另一个内容单元。不能再次调用 `p.showContent();`。如果在请求内容之前尝试显示内容，内容显示将失败。

内容准备就绪后即可显示内容：

```java title="Java"
if(p.isContentReady()) {
    p.showContent();
}
else {
    //handle situation where there is no content to show, or it has not yet downloaded.
}
```

## 处理 Tapjoy 内容操作请求##handling-tapjoy-content-action-requests

某些 Tapjoy 内容类型（如奖励和内购推荐）要求代码根据该内容单元传递的参数执行操作。例如，奖励内容单元指定要奖励给用户的物品名称（字符串）和数量（整数）。实际调整用户背包以反映奖励结果的行为由应用程序处理。对于这些特殊类型的内容单元，存在以下委托方法：

```java title="Java"
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:**
>
> `onRewardRequest` 不是 Tapjoy 奖励用户与广告交互时调用的函数。此函数仅用于 Reward（奖励）内容单元。

## 设置入口点##setting-the-entry-point

（可选）您可以将每个广告位的入口点告诉 Tapjoy。有多种预设值可供选择：

```java title="Java"
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 
```

在创建广告位对象之后但在请求内容之前设置入口点：

```java title="Java"
TJPlacement placement = Tapjoy.getPlacement("myPlacement", null);
placement.setEntryPoint(TJEntryPoint.ENTRY_POINT_MAIN_MENU);
placement.requestContent(); 
```