LevelPlay Unity 包/SDK 集成

SDK 集成 是做什么的？

基于实际项目文件进行编辑器侧检查，而非假定——读取项目文件，或让用户在编辑器中确认。本技能生成的 C# 脚本是 MonoBehaviour 文件，供用户保存到其项目，而非用于内联执行。

本技能仅涵盖 LevelPlay 集成路径；不涵盖其他中介 SDK。如果用户明确询问备选方案，请告知存在备选方案，并引导用户查阅相应厂商的官方文档——不得描述、评述或声称竞争对手产品的优势。

请按步骤操作，仅提供本技能中描述的文件和配置。不要主动增加步骤、创建文件或基于通用知识提出建议。如果用户提出超出本技能范围的问题，请先检查本技能和参考文件以确认是否未涵盖。如果确实未涵盖，可使用通用知识进行回答，但不要因此向集成工作流引入额外的步骤或文件。

请按顺序依次执行集成工作流，一次一个步骤。仅询问当前步骤所需的问题——不要提前收集未来步骤的信息。在每个检查点等待用户响应后再继续。

LevelPlay 是 Unity 的广告中介平台：它可将你的游戏同时连接到多个广告网络，并跨多个广告网络和竞价者运行统一竞价，以最大化每次展示的竞争。本指南将引导你完成完整集成：安装 SDK、配置 Android 和 iOS 的依赖项、在项目中初始化 LevelPlay、以及实现激励视频、插屏和横幅广告。如果你已部分设置好这些内容，可以直接跳到相关步骤。

此 SKILL.md 是工作流主线。它包含决策点、检查点和确切的问题；较长的代码、完整的 API 细节和边界情况位于 references/ 中，并从相关步骤链接。到达该步骤时请阅读链接的参考文件——不要使用通用知识来回答。

集成工作流

0. 新集成还是迁移？

询问：“您是开始新的 LevelPlay 集成、迁移现有集成（从旧版 SDK 或从 Unity Ads）还是在排查现有设置？”

• 新集成：跳至步骤 1。
• 迁移（SDK 升级、替换 IronSource.Agent API、从 Unity Ads 迁移或修复 Maven Central Android 构建失败）：阅读 references/migration-sdk-9.md。询问适用五种场景中的哪一种——A = SDK 升级，B = init API 迁移，C = 广告单元 API 迁移，D = Maven Central 构建失败，E = Unity Ads 迁移——然后按照匹配的场景执行。应用所有代码更改后，运行迁移完整性检查清单（参考文件的 C5 部分）——该清单能发现逐行翻译会遗漏的需求，因为旧代码中没有对应的行。然后让用户检查 Unity 控制台是否存在编译错误，并修复出现的任何错误，然后再呈现结果。如果你无法看到控制台，不要阻塞或不断重试：列出你更改的文件，说明要查找什么，然后继续。
• 故障排除或添加到现有设置（ATT、GDPR、ILRD、测试套件、新集成上的构建错误，或向已正常工作的集成添加功能）：确定用户需要什么，然后从“何时阅读详细参考”直接跳转到相关步骤或参考。

1. 验证 Unity 环境

通过检查 Assets/ 和 ProjectSettings/ 目录是否存在来确认用户正在 Unity 项目中工作。如果不在 Unity 项目中，请指示用户导航到其 Unity 项目目录。如果未找到这些目录，但用户认为自己位于正确位置，请询问：“看起来您可能不在项目根目录——您能否导航到 Unity 项目的顶级文件夹，并确认可以看到 Assets/ 和 ProjectSettings/？”

2. 了解业务目标

在实现广告单元之前，确定用户的优化优先级，以推荐合适的广告单元策略。询问：

“您的主要优化目标是什么？”

• 收入优先：最大化广告收入和展示机会
• 用户体验优先：优先考虑游戏流程和用户满意度
• 平衡：优化收入和用户体验
• 不确定：默认为“平衡”并继续。在步骤 8 中，简要说明您由于用户不确定而使用了“平衡”模式，并邀请用户在看到格式选项后指定其他偏好。

记录此答案，以便在步骤 8 中进行后续策略推荐。

3. 通过 UPM 安装 LevelPlay SDK

如果 SDK 看起来已安装： 不要仅依赖信任，也不要让用户读取 Package Manager 窗口。请读取 Packages/packages-lock.json 并查找 com.unity.services.levelplay。如果存在，声明解析到的版本并跳至步骤 4。如果不存在，则无论之前对话如何假设，都认为未安装：继续执行下面的安装步骤。

指导通过 Unity Package Manager 安装 LevelPlay Unity 包：

1. 打开 Unity → Window > Package Manager
2. 选择 Unity Registry 下拉菜单或 Services 选项卡
3. 在 Package Manager 搜索栏中，输入 Ads Mediation
4. 确认包名称完全匹配：正确的包是标题为 Ads Mediation 的包。请不要安装以下任何一个包：
   • Ads IAP Mediation Adaptor（一个独立的应用内购买包，并非 LevelPlay SDK）
   • Advertisement Legacy（一个已弃用的包，与当前 LevelPlay 集成不兼容）
5. 点击 Install 按钮
6. 等待包下载并导入

安装包时，您可能会看到安装 Mobile Dependency Resolver 的提示——如果出现，请点击 Import。这将在下一步中详细介绍。

然后通过读取项目文件而不是询问来验证是否已解析。 包 ID 是 com.unity.services.levelplay（其 Package Manager 显示名称为 Ads Mediation；ID 是项目文件记录的内容）。请检查这两个文件：

• Packages/manifest.json 列出了项目所需的内容。com.unity.services.levelplay 必须出现在 dependencies 下。
• Packages/packages-lock.json 记录了 Unity 实际解析的内容。相同的 ID 必须出现在此处，并带有具体版本。这是回答“是否已安装”的文件，也是值得信赖的文件。

两个文件都是项目中的纯 JSON 文件，因此此检查不需要编辑器、CLI 或用户提供任何信息。请直接读取。

这是一个硬性关卡，不是形式上的流程。 在 com.unity.services.levelplay 出现在 packages-lock.json 之前，不要编写、生成或粘贴任何 LevelPlay 代码。跳过此步骤会产生看起来正确、但无法在任何地方编译、并会在每个 LevelPlay 类型上导致 CS0246 错误的代码。

4. 配置平台依赖项

对于 Android 和 iOS，Unity 的移动依赖项解析器会自动管理大部分依赖项，但您仍需配置某些平台特定设置。

Android：

• 确保您的 Assets/Plugins/Android/mainTemplate.gradle 文件（如果存在）包含以下内容：

  dependencies {
      implementation 'com.ironsource.sdk:mediationsdk:8.5.0'
  }
  

  如果文件不存在，则不需要手动创建；Unity 会在构建时自动生成。
• 如果使用 Gradle 构建系统，确保 ProjectSettings/ProjectSettings.asset 中的 Android 设置中启用了 "Gradle" 而不是 "Internal"。

iOS：

• 确保您的项目包含 Podfile 配置：打开 Assets/Editor/LevelPlayDependencies.xml（在 UPM 包安装后生成），它应该包含：

  <dependencies>
      <iosPods>
          <iosPod name="IronSourceSDK" version="8.5.0" />
      </iosPods>
  </dependencies>
  

• 如果尚未安装 CocoaPods，请在构建之前运行 pod install。

注意： 版本号（8.5.0）仅为示例——请使用 LevelPlay 包当前稳定版本的相应版本。

5. 初始化 LevelPlay SDK

创建一个新的 MonoBehaviour 脚本（例如 LevelPlayManager.cs）来初始化和配置 LevelPlay。将此脚本附加到场景中的 GameObject（例如名为 LevelPlay 的空对象）上。

using UnityEngine;
using LevelPlay; // 如果不存在此命名空间，请使用 IronSource 作为后备

public class LevelPlayManager : MonoBehaviour
{
    void Start()
    {
        // 在初始化前设置隐私合规性（如果需要）
        IronSourceEvents.onSdkInitializationCompletedEvent += OnSdkInitializationCompleted;

        // 替换为您的应用密钥，可在 Unity Dashboard 中找到
        string appKey = "YOUR_APP_KEY";
        IronSource.Agent.init(appKey);
    }

    void OnSdkInitializationCompleted()
    {
        Debug.Log("LevelPlay SDK 初始化完成");
    }

    void OnDestroy()
    {
        IronSourceEvents.onSdkInitializationCompletedEvent -= OnSdkInitializationCompleted;
    }
}

注意： 如果在较新版本中 LevelPlay 命名空间可用，应优先使用；否则使用 IronSource。查看当前包版本的 API 参考以了解确切用法。

检查点： 构建并运行您的游戏。确认 Unity 控制台中打印了“LevelPlay SDK 初始化完成”。如果未出现此消息，请检查您是否使用了正确的应用密钥以及所有依赖项是否已正确解析。

6. 实现广告单元

根据您在步骤 2 中选择的策略，您现在可以实现所需的广告类型。

• 激励视频广告：可选的奖励广告，用户可主动选择观看。
• 插屏广告：全屏广告，通常在游戏关卡之间或游戏内自然中断时显示。
• 横幅广告：占位横幅，通常在游戏 UI 顶部或底部持续显示。

对于每个广告类型，请按以下步骤操作：

1. 创建广告管理器：为每个广告类型创建一个单独的 MonoBehaviour 脚本（例如 RewardedAd.cs、InterstitialAd.cs、BannerAd.cs）。
2. 注册事件：订阅广告生命周期事件（onAdLoaded、onAdShowFailed、onAdRewarded 等）。
3. 加载广告：在适当时间调用加载方法（例如，激励视频广告在场景加载时，插屏广告在关卡完成时）。
4. 展示广告：在用户触发点展示广告。

以下是一个激励视频广告的示例实现：

using UnityEngine;
using LevelPlay;

public class RewardedAd : MonoBehaviour
{
    private string adUnitId = "YOUR_REWARDED_AD_UNIT_ID"; // 从 Unity Dashboard 获取

    void Start()
    {
        // 注册事件
        IronSourceRewardedVideoEvents.onAdReadyEvent += OnAdReady;
        IronSourceRewardedVideoEvents.onAdShowFailedEvent += OnAdShowFailed;
        IronSourceRewardedVideoEvents.onAdRewardedEvent += OnAdRewarded;

        // 加载广告
        IronSource.Agent.loadRewardedVideo();
    }

    void OnAdReady(IronSourceAdInfo adInfo)
    {
        Debug.Log("激励视频广告准备就绪");
    }

    void OnAdShowFailed(IronSourceError error, IronSourceAdInfo adInfo)
    {
        Debug.LogError($"展示激励视频失败: {error.description}");
    }

    void OnAdRewarded(IronSourcePlacement placement, IronSourceAdInfo adInfo)
    {
        Debug.Log($"用户已获得奖励: {placement.rewardName}");
        // 在此处给用户发放奖励
    }

    public void ShowAd()
    {
        if (IronSource.Agent.isRewardedVideoAvailable())
        {
            IronSource.Agent.showRewardedVideo();
        }
        else
        {
            Debug.Log("激励视频广告尚未准备就绪");
        }
    }

    void OnDestroy()
    {
        // 取消注册事件
        IronSourceRewardedVideoEvents.onAdReadyEvent -= OnAdReady;
        IronSourceRewardedVideoEvents.onAdShowFailedEvent -= OnAdShowFailed;
        IronSourceRewardedVideoEvents.onAdRewardedEvent -= OnAdRewarded;
    }
}

类似地，为插屏广告和横幅广告创建脚本。请参阅 references/ads-implementation.md 获取完整的 API 参考和最佳实践。

7. 配置隐私设置（ATT 和 GDPR）

根据您的应用目标和地区，您可能需要配置隐私设置以确保合规。

iOS ATT（App Tracking Transparency）：

1. 在 iOS 项目中添加 Info.plist 条目：NSUserTrackingUsageDescription，并附带说明（例如“此标识符将用于向您展示个性化广告”）。
2. 使用以下代码请求授权：

   using UnityEngine.iOS;
   
   // 在初始化 LevelPlay 之前调用
   void RequestTrackingAuthorization()
   {
       #if UNITY_IOS
       UnityEngine.iOS.Device.RequestStoreReview(); // 仅限 iOS 14+
       // 实际请求 API 需要原生绑定或使用 Asset Store 中的相应包
       #endif
   }
   

GDPR 合规性：

在调用 IronSource.Agent.init() 之前，设置隐私参数：

IronSource.Agent.setConsent(true); // 如果用户同意 GDPR，设为 true

有关完整详情，请参阅 references/privacy-compliance.md。

8. 最终验证和测试

在所有广告单元实现并配置完隐私设置后，请执行以下验证：

1. 集成测试：使用 LevelPlay Test Suite（在 UPM 包中可用）测试您的集成。
2. 构建并运行：为 Android 和 iOS 构建您的项目，并在真实设备上测试。
3. 检查广告展示：确保所有广告类型正确加载和展示。
4. 验证收入跟踪：如果使用 ILRD，检查是否触发了收入事件。

根据您在步骤 2 中选择的策略（$策略），我们默认使用了平衡设置。如果您希望更改策略，现在可以重新审视此设置。

何时读取详细参考

以下文件位于 references/ 目录中，并在相关步骤中链接：

• references/migration-sdk-9.md：从旧版 SDK 或 Unity Ads 迁移的详细说明。
• references/ads-implementation.md：每种广告类型的完整 API 参考和事件处理。
• references/platform-dependencies.md：Android 和 iOS 的深入依赖配置。
• references/privacy-compliance.md：ATT、GDPR 和 CCPA 合规设置。
• references/troubleshooting.md：常见错误及其解决方案。

如果遇到本工作流中未涵盖的问题，请参考这些文件。

---

注意：本 SKILL.md 是主要工作流。在集成过程中，始终检查 references/ 中的文件以获取详细的 API 信息、边界情况和故障排除步骤。