> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 集成

> Unity SDK 完整集成指南

CloudX Unity SDK 使您能够在 iOS 和 Android 上通过横幅、MREC、插屏和激励广告实现 Unity 游戏变现。

## 安装

CloudX Unity SDK 以 `.unitypackage` 文件形式分发。

1. 从 [GitHub Releases](https://github.com/cloudx-io/cloudx-unity/releases) 下载最新的 `CloudXSdk-4.1.7.unitypackage`
2. 在 Unity 中，转到 **Assets > Import Package > Custom Package**
3. 选择下载的 `.unitypackage` 文件
4. 提示时导入所有资源

<Info>
  External Dependency Manager 将自动解析 Android 和 iOS 依赖。
</Info>

## 广告网络适配器

CloudX SDK 需要广告网络适配器来投放广告。在 `Assets/CloudXSdk/Editor/CloudXDependencies.xml` 中取消注释相应行即可启用。各适配器的详细设置（包括 iOS Info.plist 要求），请参阅[适配器](/zh/unity/adapters/meta)章节。

<Note>
  SDK 至少需要一个适配器才能投放广告。
</Note>

## 初始化

在加载任何广告之前初始化 SDK。您可以在初始化之前选择性地配置用户和应用属性。

```csharp theme={null}
using CloudX;
using UnityEngine;

public class MyGameManager : MonoBehaviour
{
    void Start()
    {
        InitializeCloudX();
    }

    void InitializeCloudX()
    {
        // 初始化前配置（可选）
        CloudXSdk.SetHashedUserId("hashed-user-id");
        CloudXSdk.SetUserKeyValue("user_level", "premium");
        CloudXSdk.SetAppKeyValue("app_version", "1.0.0");

        // 在初始化之前订阅回调
        CloudXInitializationCallbacks.OnSdkInitializedEvent += OnSdkInitialized;
        CloudXInitializationCallbacks.OnSdkInitializationFailedEvent += OnSdkInitializationFailed;

        // 初始化 SDK
        var config = CloudXInitializationConfiguration.Create("YOUR_APP_KEY").Build();
        CloudXSdk.Initialize(config);
    }

    private void OnSdkInitialized(CloudXSdkConfiguration config)
    {
        Debug.Log("CloudX SDK 初始化成功");
        // 现在可以加载广告
    }

    private void OnSdkInitializationFailed(CloudXError error)
    {
        Debug.LogError($"SDK 初始化失败: {error}");
    }
}
```

<Note>
  在调用 `Initialize()` 之前订阅 `CloudXInitializationCallbacks` 事件以接收初始化结果。
</Note>

## 广告格式

CloudX Unity SDK 支持横幅、MREC、插屏和激励广告集成。请查阅各格式专属指南了解实现详情：

<CardGroup cols={2}>
  <Card title="横幅广告和 MREC 广告" href="/zh/unity/ad-formats/banner-mrec">
    在固定屏幕位置展示广告，支持可选刷新控制。
  </Card>

  <Card title="插屏广告" href="/zh/unity/ad-formats/interstitial">
    加载并展示全屏插屏广告。
  </Card>

  <Card title="激励广告" href="/zh/unity/ad-formats/rewarded">
    用户完成激励广告观看后给予奖励。
  </Card>
</CardGroup>

## 高级功能

### 隐私控制

如果您的应用没有使用 CMP，可以在初始化之前手动覆盖隐私状态。

```csharp theme={null}
// 在 Initialize() 之前可选地设置手动隐私覆盖
CloudXSdk.SetHasUserConsent(true);
CloudXSdk.SetDoNotSell(false);

// 传入 null 可清除手动覆盖，重新交由 CMP 或 IAB 信号决定
CloudXSdk.SetHasUserConsent(null);
CloudXSdk.SetDoNotSell(null);
```

* `SetHasUserConsent(bool?)` 用于设置 GDPR 同意覆盖。
* `SetDoNotSell(bool?)` 用于设置 CCPA do-not-sell 覆盖。
* 如果存在 IAB 同意或隐私信号，它们会优先于这些手动覆盖值。

### iOS ATT 使用说明文案

从 Unity SDK `2.2.4` 开始，如果您的应用尚未在 `Info.plist` 中定义 `NSUserTrackingUsageDescription`，CloudX 的 iOS 后处理步骤会自动添加该字段。

* 默认值：`This uses device info for more personalized ads and content`
* 如果您已经提供了 `NSUserTrackingUsageDescription`，CloudX 会保留您现有的值不变。
* 如果您希望展示自定义的 ATT 提示文案，请在 `Info.plist` 中显式设置自己的值。

### 用户定向

配置用户和应用属性以获得更好的广告定向。在 `Initialize` 之前调用这些方法。

```csharp theme={null}
// 设置哈希用户 ID
CloudXSdk.SetHashedUserId("hashed-user-id-12345");

// 设置用户级键值对
CloudXSdk.SetUserKeyValue("user_level", "premium");
CloudXSdk.SetUserKeyValue("age_group", "25-34");

// 设置应用级键值对
CloudXSdk.SetAppKeyValue("app_version", "1.0.0");
CloudXSdk.SetAppKeyValue("build_number", "123");

// 清除所有自定义键值对
CloudXSdk.ClearAllKeyValues();
```

### 收入追踪

所有广告格式都通过 `OnAdRevenuePaid` 事件提供收入回调。`CloudXAd` 对象包含收入信息：

```csharp theme={null}
CloudXAdsCallbacks.Banner.OnAdRevenuePaid += (ad) =>
{
    Debug.Log($"收入: ${ad.Revenue:F4}");
    Debug.Log($"广告网络: {ad.NetworkName}");
    Debug.Log($"广告单元: {ad.AdUnitId}");
    Debug.Log($"广告格式: {ad.AdFormat}");
    Debug.Log($"广告位: {ad.Placement}");
    Debug.Log($"网络广告位: {ad.NetworkPlacement}");

    // 在您的分析中追踪收入
    TrackRevenue(ad.Revenue, ad.NetworkName);
};
```