# SDK

> 查看 Tapjoy 的 iOS SDK 参考，了解如何请求广告位、处理回调、显示广告内容以及集成核心 SDK 函数。

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

首先，在文件顶部导入 `TJPlacement.h`。

1. **Objective-C**

   ```objective-c title="Objective-C" 
   #import <Tapjoy/TJPlacement.h>
   ```

2. **Swift**

   ```swift
   // Import already happens automatically through your bridging header
   ```

然后，创建 TJPlacement 类的一个实例，并使用广告位名称对其进行初始化。确保代码中的广告位名称字符串与后台中的广告位名称完全匹配。还可以实现委托来接收回调（下文对此进行了说明）。

1. **Objective-C**

   ```objective-c title="Objective-C"
   TJPlacement *p = [TJPlacement placementWithName:@"Main Menu" delegate:self];
   ```

2. **Swift**

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

最后，请求内容。

1. **Objective-C**

   ```objective-c title="Objective-C"
   [p requestContent];
   ```

2. **Swift**

   ```swift
   p?.requestContent()
   ```

在请求内容之前，请确保 Tapjoy connect 调用已成功。观察到 TJC\_CONNECT\_SUCCESS 通知之前，请勿发起请求。

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

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

## TJPlacement 回调##tjplacement-callbacks

要获取有关内容请求状态的反馈，请实现以下 TJPlacementDelegate 方法：

1. **Objective-C**

   ```objective-c title="Objective-C"
   - (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{}
   ```

2. **Swift**

   ```swift
   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

要实际显示内容，请调用 show：

1. **Objective-C**

   ```objective-c title="Objective-C"
   [p showContentWithViewController：nil];
   ```

2. **Swift**

   ```swift
   p.showContent(with: nil)
   ```

如果向 `showContentWithViewController` 传递“nil”，Offerwall SDK 将创建自己的视图控制器 (view controller) 来处理广告的显示。在大多数情况下，这是最安全的选项。如果您的视图层级结构很复杂，并且出于某种原因希望自己管理广告显示，则可以选择将您自己的视图控制器传递给 `showContentWithViewController`。必须确保传递给此方法的 ViewController 是最顶层的视图，此视图未被其他视图遮挡，并且在 Tapjoy 内容被移除之前，其他视图没有置于此视图之上。

在调用 show 之前，请进行检查以确保内容已准备就绪：

1. **Objective-C**

   ```objective-c title="Objective-C"
   if (p.isContentReady) {
      [p showContentWithViewController：nil];
   }
   else {
     //handle situation where there is no content to show, or it has not yet downloaded.
   }    
   ```

2. **Swift**

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

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

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

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

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

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

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

1. **Objective-C**

   ```objective-c title="Objective-C"
   - (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 
   }    
   ```

2. **Swift**

   ```swift
   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

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

1. **Objective-C**

   ```objective-c title="Objective-C"
   TJEntryPointUnknown //Not set, but removes any value that was already set
   TJEntryPointOther
   TJEntryPointMainMenu
   TJEntryPointHud
   TJEntryPointExit
   TJEntryPointFail
   TJEntryPointComplete
   TJEntryPointInbox 
   TJEntryPointInitialisation
   TJEntryPointStore 
   ```

2. **Swift**

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

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

1. **Objective-C**

   ```objective-c title="Objective-C"
   TJPlacement *placement = [TJPlacement placementWithName:@"myPlacement" delegate:nil];
   [placement setEntryPoint:TJEntryPointMainMenu];
   [placement requestContent]; 
   ```

2. **Swift**

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