# 快速入门

> 将 Tapjoy Unity 插件导入到项目中以启用 SDK 集成。快速入门指南将引导您完成导入 .unitypackage、配置 SDK 密钥以及添加所需的 Tapjoy 游戏对象等步骤。

## SDK 集成##sdk-integration

为了与应用集成，第一步是[下载 Unity SDK](https://sdk.tapjoy.com/releases/14.8.0/TapjoyUnityPlugin_v14.8.0.zip) 本身。

Tapjoy Unity 插件的 zip 文件包含一个便于导入的 Unity 包文件，还有一些原始文件适合喜欢拖放文件进行 Tapjoy 升级的用户。要导入 `TapjoyUnityPlugin_vVERSION.unitypackage`，请执行以下操作：

1. 打开您的 Unity 项目。
2. 转到 **Assets（资源）**> **Import Package（导入包**）> **Custom Package（自定义包）**。
3. 指向 `TapjoyUnityPlugin_vVERSION.unitypackage` 文件。
4. 查看导入文件列表，检查是否存在任何冲突。
5. 选择 \*\*Import（导入）\*\*以接受这些文件。

> **Note:**
>
> 从 12.8.0 开始，Offerwall SDK 现由 External Dependency Manager 使用 Cocoapods 进行管理。确保 Cocoapods 版本为 1.9.0 或更高版本，且 Xcode 版本为 11.0 或更高版本。

### 在 Unity 5.4 或更高版本上更新##updating-on-unity-5.4-or-higher

如果要更新集成且使用的是 Unity 5.4 或更高版本，则会显示“Fix（修复）”按钮以用于修复一个错误，这个错误会导致 Google Play 服务库被标记为包含在 iOS 构建中。

选择 \*\*Fix（修复）\*\*可以确保 Google Play 服务仅包含在 Android 构建中。对于 Unity 5.4 之前的版本，您需要手动确保 google-play-services\_lib 设置为仅包含在 Android 构建中。请注意，新集成不需要进行这种修复，也不会显示此按钮。

### 添加应用权限（适用于 Android）##add-app-permissions-(for-android)

（可选）将 `ACCESS_WIFI_STATE` 权限包含在清单中：

```java
<manifest ...>
  ...
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
  ...
</manifest>
```

## 连接到 Tapjoy##connect-to-tapjoy

您可以在 Tapjoy 窗口中开始配置 Tapjoy。转到 `Window > Tapjoy`（窗口 > Tapjoy）打开 Tapjoy 窗口。

![游戏中 Unity Offerwall 窗口的示例。](/api/media?file=/grow/media/images/tapjoy_window_screenshot.png)

在 Tapjoy 窗口中，可进行以下配置：

* 设置 Android 和 iOS 的 SDK 密钥
* 添加 Android 市场的商店名称（例如，Google 或 Amazon）
* 启用或禁用广告 ID、持久 ID 和 IDFA
  * **Disable Advertising Id（禁用广告 ID）**：此复选框与 Android 中的 **DISABLE\_ADVERTISING\_ID\_CHECK** 连接标志具有相同的效果。默认情况下，Tapjoy 的 Android SDK 会检查是否存在 Google 广告标识符，如果没有找到，初始化将失败。选中此复选框可以禁用这一检查，使 Offerwall SDK 即使在没有 Google 广告标识符的情况下也能初始化。当应用中不存在 Google Play 服务时（例如，在非 Google Play 应用商店中构建发布版本时），此选项很有用。
  * **Disable Persistent Ids（禁用持久 ID）**：此复选框与 Android 中的 **DISABLE\_PERSISTENT\_IDS** 连接标志具有相同的效果。Offerwall SDK 会将持久标识符（例如 MAC 地址和 Android 标识符）发送到 Tapjoy 服务器，以便在广告标识符不可用的情况下用作备用广告标识符（这是 [Play Console 帮助文档关于广告 ID 的部分](https://support.google.com/googleplay/android-developer/answer/6048248)中建议的选项）。如果设置此标志，则仅当广告标识符在 SDK 中不可用时，才会将持久标识符发送到 Tapjoy 服务器来跟踪广告主。
  * 没有复选框等效于 **DISABLE\_ANDROID\_ID\_AS\_ANALYTICS\_ID** 连接标志。（如果设置此标志，Tapjoy 用于分析目的的 ID 不再是 Android ID 的副本，而是随机生成的字符串。如果发布新的构建时更改了此标志的设置以使其不同于旧版本，则可能导致某些现有用户被 Tapjoy 的分析工具识别为新用户。）如果想要设置此标志，必须使用 [Tapjoy Unity 手动连接](#manual-connect)并添加 **DISABLE\_ANDROID\_ID\_AS\_ANALYTICS\_ID** 标志。
* 设置日志记录级别

还可以检查集成的状态，包括 GCMReceiver Setting（GCMReceiver 设置）和 Install Referrer Receiver Setting（安装来源接收器设置）。

为了使 Offerwall SDK 正常工作，需要一个附加了 TapjoyComponent 的 TapjoyUnity 游戏对象 – 在编辑器窗口中将有一个“Fix（修复）”按钮，此按钮将自动为您添加和设置这个游戏对象。仅将 Tapjoy 游戏对象添加到游戏中首次出现的第一个场景。

完成 Tapjoy 的配置后，即可构建和运行您的应用程序。

### 最大用户等级##max-user-level

您可以告诉 Tapjoy 您的游戏中有多少关卡。此值可以在调用 connect 之前或之后设置。

```csharp
Tapjoy.SetMaxLevel(10); 
```

### 用户细分段##user-segment

您可以通过调用 `setUserSegment` 将用户标识为某个细分段的一部分。此设置可以在调用 connect 之前或之后进行。

```csharp
Tapjoy.SetUserSegment(TJSegment.VIP);
Tapjoy.SetUserSegment(TJSegment.Payer);
Tapjoy.SetUserSegment(TJSegment.NonPayer);
Tapjoy.SetUserSegment(TJSegment.Unknown); 
```

### 手动连接##manual-connect

Unity SDK 允许通过代码来控制连接步骤。默认情况下，SDK 将为您处理连接。要启用手动控制，请先在 Tapjoy Settings（Tapjoy 设置）窗口（Window（窗口）> Tapjoy）中取消选中“Auto-Connect（自动连接）”选项。

取消选中该选项后，SDK 将不再自动为您处理连接。您需要使用代码自行处理连接，这种行为与原生 SDK 中的行为类似。

当应用程序首次启动时，必须调用 `Connect` 使 SDK 连接到 Tapjoy 服务器。Connect 函数有两个版本。Connect 函数的第一个版本仅接受字符串形式的 SDK 密钥。如果您的应用程序面向多个平台，则需要为每个平台提供正确的 SDK 密钥。

```csharp
#if UNITY_ANDROID
		Tapjoy.Connect("your_android_sdk_key");
#elif UNITY_IOS
		Tapjoy.Connect("your_ios_sdk_key");
#endif
```

Connect 函数的另一个版本接受第二个参数，即字符串/字符串值字典。此字典是您的 connectFlags，其行为与原生 SDK 中的行为相同。

```csharp
Dictionary<string,string> connectFlags = new Dictionary<string,string>();
connectFlags.Add("TJC_OPTION_USER_ID", "<USER_ID_HERE>");

#if UNITY_ANDROID
  Tapjoy.Connect("your_android_sdk_key", connectFlags);
#elif UNITY_IOS
  Tapjoy.Connect("your_ios_sdk_key", connectFlags);
#endif
```

还可以使用编程的方式获取和设置日志记录级别。

```csharp
// Set logging level
Tapjoy.SetLoggingLevel(LoggingLevel.Debug);

// Get logging level
LoggingLevel loggingLevel = Tapjoy.GetLoggingLevel();
```

必须先完成 SDK 连接，然后才能使用 SDK 执行其他操作（例如，加载广告）。有两个在发生连接事件时触发的事件委托 – OnConnectSuccess 和 OnConnectFailure。应声明委托函数来监听连接事件。触发 onConnectSuccess 后，即可开始使用其他 SDK 函数。

如果 SDK 无法连接，可调用不带参数的 Connect() 来重新尝试连接。这样，SDK 将使用上次尝试连接时使用的 SDK 密钥重试连接。

### 回调##callbacks

SDK 运行起来后，现在可以花点时间按照最佳实践编写代码了。Offerwall SDK 需要先成功连接到我们的服务器，然后才能请求广告或发送追踪数据。SDK 公开了一个委托函数 `OnConnectSuccess`，这个函数将在 SDK 成功连接时触发。请等待 SDK 成功连接后再尝试使用其他函数（例如请求广告或追踪数据）。当连接过程中出现非阻塞问题时，`OnConnectWarning` 回调将触发（`connectSuccess` 也会在之后触发）。目前，这种检测功能仅在通过 ConnectFlags 发送 UserId 时才会检测 UserId 的问题。`OnConnectFailure` 表示发生错误且 SDK 未连接。

```csharp
Tapjoy.OnConnectSuccess += HandleConnectSuccess;
...

public void HandleConnectSuccess() {
    Debug.Log ("Connect Success");

    // Now that we are connected we can start preloading our placements
    TJPlacement p = TJPlacement.CreatePlacement("my_placement");
    p.RequestContent();
}

Tapjoy.OnConnectWarning += HandleConnectWarning;
...

void HandleConnectWarning(int code, string message)
{
    
}

Tapjoy.OnConnectFailed += HandleConnectFailed
...

public void HandleConnectFailed(int code, string message){

}
```

还可检查 `Tapjoy.isConnected` 布尔值来检查 SDK 连接状态。