levelplay-unity-integration

LevelPlay Unity 软件包/SDK 集成

编辑器侧检查应基于实际项目，而不是假设——请读取项目文件，或让用户在 Editor 中确认。本技能生成的 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 = 初始化 API 迁移，C = 广告单元 API 迁移，D = Maven Central 构建失败，E = Unity Ads 迁移——然后按照对应情况操作。应用所有代码更改后，完成 Migration Completeness Checklist（参考资料的 C5 节）——它能发现逐行转换时遗漏的要求，因为旧代码中没有对应的代码行。然后请用户检查 Unity 控制台中的编译错误，并在展示结果前修复所有已出现的错误。如果你无法查看控制台，不要因此阻止流程或反复尝试：列出你修改的文件，说明需要检查什么，然后继续。
• 故障排查或为现有设置添加内容（ATT、GDPR、ILRD、Test Suite、新集成中的构建错误，或为已正常运行的集成添加功能）：确定用户的需求，然后直接跳转到“何时阅读详细参考资料”中的相关步骤或参考资料。

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 文件，因此无需 Editor、CLI，也不需要用户提供任何信息即可完成检查。读取它们。

这是必须通过的门槛，不是走过场。 在 com.unity.services.levelplay 出现在 packages-lock.json 之前，不要编写、生成或粘贴任何一行 LevelPlay 代码。跳过这一步会产生看似正确、却无法编译的代码，并且每个 LevelPlay 符号都会报 CS0246 错误。如果该 ID 不在 manifest.json 中，说明安装从未发生。如果它在 manifest.json 中，却不在 packages-lock.json 中，说明 Unity 尚未解析该包：Editor 可能仍在导入，也可能解析失败。说明你检查到的是哪种情况，然后停止。

如果你自行将 ID 添加到 manifest.json，且之后尚未运行过 Editor，那么锁定文件中还不会显示它。这是预期情况，并不代表失败。 切勿自行将条目写入 packages-lock.json：该文件是 Unity 的解析输出，迁移指南明确禁止手动编辑；自行写入的条目只是虚假的“已解析”信号，并不代表通过了门槛。请让用户打开 Unity Editor 以运行解析，然后重新读取该文件。如果完全无法使用 Editor，请说明这一点并就此停止，不要伪造证据。

报告你查到的已解析版本。不要仅凭 Package Manager 窗口、之前的对话或用户的回忆就报告“已安装”。

Network Manager： 随时访问 Ads Mediation > Network Manager，即可安装其他广告网络适配器，并检查 SDK 和适配器更新。

对于 iOS 构建，请注意后续需要配置 SKAdNetwork（准备进行 iOS 构建时，请参考 references/ios-setup.md）。

4. 解析原生依赖项（关键）

对 Android/iOS 构建至关重要：LevelPlay 需要解析原生依赖项。如果不进行此操作，代码虽然能在 Unity Editor 中编译，但在平台构建时会因 gradle（Android）或 CocoaPods（iOS）错误而失败。

平台确认点 — 继续之前请先询问：“你的目标平台是哪些——iOS、Android，还是两者都包括？”记录答案。这将决定此处适用哪些依赖项解析步骤、是否需要 ATT（步骤 6.5），以及哪些测试步骤相关（步骤 10）。

**现在设置当前构建目标。**通过 File ▸ Build Profiles（Unity 6 之前称为 Build Settings）→ Switch Platform，将项目的当前构建目标切换为 Android 或 iOS。任何测试之前都必须完成此操作：LevelPlay 仅在 Android/iOS 目标上运行，因此当目标为 Standalone/PC/Mac 时，即使在 Editor 中使用模拟广告（步骤 10）也不会生效。

**为目标平台解析依赖项。**LevelPlay 需要 Unity 包管理器无法单独处理的 Android/iOS 原生库；依赖项管理器（MDR、UEDM 或 EDM4U）可弥补这一缺口。完整流程——检查是否已有依赖项管理器、解析 Android 与 iOS 上的依赖项、在用户没有依赖项管理器时安装一个、验证，以及旧版本中的 Custom Main Gradle Template——详见 references/dependency-resolution.md。现在引导用户完成此流程；如果目标平台同时包括 Android 和 iOS，请在继续之前完成这两个平台的依赖项解析。

询问：“你是否已为目标平台完成依赖项解析，且没有遇到错误？”

**Android API 33+（Android 13+）：**在 AndroidManifest.xml 中声明 AD_ID 权限：

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

如果不声明，Android 13+ 设备将无法访问广告 ID。详情请参阅 references/dependency-resolution.md。

如果依赖项解析失败，请参阅 references/troubleshooting.md，了解 gradle 和 CocoaPods 错误的处理方法。

5. 获取 App Key 和广告单元 ID

初始化 LevelPlay 之前，请从 LevelPlay 控制面板获取凭据。

控制面板： https://platform.ironsrc.com/

**初次使用 LevelPlay？**请先设置应用和广告单元：

• 添加你的应用
• 创建广告单元

**App Key：**在控制面板左侧导航栏中，前往 Apps → 找到你的应用 → 复制应用标题下显示的字母数字字符串。

**广告单元 ID：**在左侧导航栏中前往 Ad units → 选择你的应用 → 复制计划实现的各个广告格式（Rewarded、Interstitial、Banner）对应的 ID。

**注意：**初始化时（步骤 7）需要 App Key。广告单元 ID 只在步骤 9 中需要——如果你还没决定要实现哪些广告格式，现在只需复制 App Key，完成步骤 8 后再返回此处即可。

请确保两者都能随时取用——接下来的步骤会用到它们。

6. 配置 AdMob Key（如果使用 AdMob 网络）

适用情形：仅在 LevelPlay 中使用 AdMob 作为聚合网络适配器时适用。

如果使用 AdMob，请在 Unity Editor 中配置平台专属应用 Key：

访问路径：Ads Mediation > Developer Settings > LevelPlay Mediation Settings

配置项：

• Android App Key：AdMob Android 应用 Key
• iOS App Key：AdMob iOS 应用 Key

若要让 AdMob 在 LevelPlay 中作为聚合网络正常工作，必须完成此配置。

故障排查：如果在 Unity Editor 中看不到“Ads Mediation”菜单，请确认已安装 Ads Mediation 包（步骤 3），然后重启 Unity Editor。

6.5. 隐私与法规设置（如有需要）

注意： 此技能提供技术集成指南，包括 LevelPlay 隐私 API 相关内容。本文不构成法律建议，也不确定哪些法律适用于你的应用——这取决于你的用户、数据实践和分发方式。请咨询你自己的法律顾问，并参阅 Unity 的法规高级设置，以获取权威的 LevelPlay 文档。

询问用户：“你是否需要为 GDPR、CCPA/CPRA（或某些州的消费者隐私法案）或面向儿童的应用配置隐私设置？”

如果任一项的回答为“是”：

必须在 SDK 初始化之前配置隐私设置。完整的实现指南（UI、同意管理、组合法规和完整的网络键列表）请参阅 references/privacy-settings.md。

GDPR — 正确的 API 取决于用户的 SDK 版本（在 Ads Mediation > Network Manager 中检查）：

SDK 9.5.0+ — 全局同意布尔值：

using Unity.Services.LevelPlay;

// true = user has granted consent, false = user has not consented
LevelPlayPrivacySettings.SetGDPRConsent(true);

SDK 9.4.x — 按网络区分的同意字典（这是 9.4.x 上的当前 API，并非旧版 API — 只有在 9.5.0+ 上才会变为 [Obsolete]；不要错误地将其标记为已弃用）：

using Unity.Services.LevelPlay;
using System.Collections.Generic;

// Add an entry for each ad network you have installed
LevelPlayPrivacySettings.SetGDPRConsents(new Dictionary<string, bool> {
    { "UnityAds", true },
    { "IronSource", true }
    // See references/privacy-settings.md for the full network key list
});

如果两个 API 都无法编译，你的 Unity 软件包/SDK 可能低于 9.4.0（旧版）——建议通过 Ads Mediation > Network Manager 升级。如果用户无法升级，旧版 LevelPlay.SetConsent(bool) API 的文档位于 references/privacy-settings.md。

CCPA（SDK 9.4.0+）：

LevelPlayPrivacySettings.SetCCPA(true); // User opted out of data sale

COPPA（SDK 9.4.0+）：

LevelPlayPrivacySettings.SetCOPPA(true); // Child-directed app

如果 CCPA 或 COPPA 无法编译，请通过 Ads Mediation > Network Manager 升级 Unity 软件包/SDK。在第 7 步调用 LevelPlay.Init() 之前调用以上所有 API。

对于 iOS 构建 — 无论上述隐私法规是否适用，都必须执行： 继续第 7 步之前，还必须实现 App Tracking Transparency (ATT)。Apple 要求在 iOS 14.5+ 上，应用跟踪用户或访问设备的广告标识符之前，先获得 ATT 授权。在调用 LevelPlay.Init() 之前请求 ATT 授权——这是 Apple 平台的要求，也是投放个性化广告的必要条件（还会影响填充率）。ATT 实现代码请参阅 references/ios-setup.md。

如果不适用任何隐私法规且不面向 iOS： 跳过此步骤并继续第 7 步。

7. 初始化 LevelPlay SDK

安装检查点：

首先，重新读取 Packages/packages-lock.json，并确认其中包含 com.unity.services.levelplay。 每次到达此处时都要执行此操作，即使本次对话中第 3 步早已通过也一样。 这只需读取一个文件，而且这是此处唯一一项无需用户确认即可核实的内容。较早的轮次中提到软件包已安装，并不能证明它确实已安装：设置步骤最容易被跳过，而由此产生的代码会在每个 LevelPlay 符号处触发 CS0246。如果缺少该 ID，请返回第 3 步，不要编写初始化代码。

然后向用户确认其余先决条件，因为这些内容无法通过文件判断。 如果用户已确认未使用 AdMob，请省略第 6 步的相关项目。 如果本次对话中已确认第 4 步，请跳过该项目，只询问第 5 步和第 6 步（如果使用 AdMob）。

“请确认以下项目均正常工作：

• 第 4 步：你是否已为目标平台运行依赖项解析，且没有错误？
• 第 5 步：你是否已从 LevelPlay 控制面板复制 App Key？
• 第 6 步（仅在使用 AdMob 时）：你是否已在 Unity Editor 设置中配置 AdMob 密钥？

请先验证这些项目均正常工作，再继续。” 如果软件包检查失败，或者他们回答“否”或不确定：

• packages-lock.json 中缺少软件包 ID：代码会显示 CS0246 命名空间错误 → 指引至步骤 3。这一点由你自行确认；不要让用户推翻这一判断。
• 缺少步骤 4：代码可以编译，但 Android/iOS 构建会失败 → 指引至步骤 4
• 缺少步骤 5：他们没有用于初始化的凭据 → 指引至步骤 5
• 在他们确认所有步骤均已完成之前，不要提供 C# 代码

如果他们回答“是”：

• 可选 — 分析：ILRD 接线。 原样提出以下问题，不要总结或改写：“您是否使用需要广告收入数据的分析或归因平台（Firebase、AppsFlyer、Adjust、Singular 或自定义后端）？如果是，初始化脚本会包含一段用于记录展示级收入（ILRD）的代码存根 — 3 行代码，目前无需设置分析平台。（是 / 否 / 不确定 — 默认为是）”记录他们的回答。
• 继续提供初始化代码。

必须先初始化 LevelPlay SDK，才能加载或展示任何广告。应在应用程序生命周期早期进行初始化。

询问他们希望如何处理初始化。按下列内容完整呈现所有四个选项，不要缩减或省略：

1. 创建一个新的专用脚本来初始化 LevelPlay
2. 添加到他们已有的初始化/管理器脚本中
3. 创建一个由现有管理器引用的新 LevelPlay 脚本
4. 只给我看初始化代码 — 我会自行决定如何集成

每个选项的完整代码见 references/initialization-api.md（代码组织选项）。 不得更改以下行为：

• 选项 1（新脚本）： 如果在步骤 6.5（iOS）中已设置 ATT，请使用 references/ios-setup.md 第 3 部分中的 LevelPlayInitializer.cs（IEnumerator Start() 协程版本），而不是普通模板。
• 选项 4（只看代码）： 提供完整的选项 1 初始化类作为独立代码片段 — 不要创建文件，也不要添加 Inspector/GameObject 设置步骤 — 并附上说明：“将其保存为 LevelPlayInitializer.cs，将其附加到第一个场景中的持久化 GameObject，并在 Inspector 中设置 App Key 字段。”

ILRD 接线（如果用户回答“是”或“不确定”）。 正确做法取决于 SDK 版本（在 Ads Mediation > Network Manager 中检查）：

• SDK 9.5.0+（当前版本）： 不要在初始化器中添加任何内容 — ILRD 会通过 OnAdImpressionDataReady 按广告实例提供，并在步骤 9 创建每个广告时接线。全局 LevelPlay.OnImpressionDataReady 事件在 9.5.0+ 中已弃用，并会产生编译器警告 — 不要使用。
• SDK 9.4.x 及更早版本： 在 LevelPlay.Init() 之前订阅全局 LevelPlay.OnImpressionDataReady 事件，添加一段记录代码存根，并在 OnDestroy() 中取消订阅。对于 iOS 协程初始化器，请将订阅放在 InitializeLevelPlay() 中，紧接在 LevelPlay.Init(appKey) 之前。

每个选项的确切接线代码（包括 iOS 协程中的放置位置）见 references/initialization-api.md（按版本区分的 ILRD 初始化接线）。模拟广告不会触发 ILRD 回调 — 需要通过设备构建进行验证（参见步骤 10）。高级选项（用户 ID、细分、同意管理）请参见 references/initialization-api.md。

8. 推荐广告单元策略

根据第 2 步确定的优化目标，推荐广告单元策略。

回顾用户在第 2 步中提到的优化目标。 如果对话已经很长，或者回答不明确，请确认：“你之前提到了自己的优化目标。确认一下，你主要关注收入、用户体验，还是两者兼顾？”

根据回答选择策略，并给出简要建议（完整详情、基准数据和展示位置指南，请参阅 references/best-practices.md 中的 “Ad Format Strategy by Goal”）：

• 关注收入 → 收入策略。 激励广告（主要变现方式，设置多个高价值时机）→ 插屏广告（次要；在流程过渡时展示；频次上限为 3–5 分钟）→ 横幅广告（游戏过程中持续展示）。底价是可选的收入杠杆，可在第 9 步配置。实现优先级：激励广告 → 插屏广告 → 横幅广告。
• 关注用户体验 → 用户体验策略。 仅使用由用户主动触发的激励广告（明确选择加入），提供高价值奖励，绝不强制展示广告。插屏广告为可选项，只在会话间隔处谨慎展示；通常应避免横幅广告，或仅在菜单中展示。实现优先级：仅激励广告，或激励广告 →（可选）插屏广告。
• 两者兼顾 → 均衡策略。 激励广告（设置 2–3 个策略性展示位置）→ 插屏广告（适度展示；选择自然停顿点；频次上限为 5–7 分钟）→ 横幅广告（有选择地在菜单或用户注意力较低时展示）。实现优先级：激励广告 → 插屏广告 → 横幅广告（有选择地展示）。
• “还不确定”（来自第 2 步）→ 使用均衡策略，然后补充：“由于你之前还不确定目标，我采用了均衡方案——如果看过这些选项后，你现在更倾向于收入或用户体验，请告诉我。”
• 如果仍不明确，请询问：“你会优先考虑收入、用户体验，还是两者兼顾？”

下一步会询问用户要从此优先级列表中实现哪些广告格式。如果用户希望采用与推荐不同的顺序，请按其偏好安排。

9. 实现广告单元

首先阅读 references/best-practices.md——其中的 “Code Generation Guidelines (Step 9)” 一节包含常规广告生命周期、针对每种组织方式的代码生成规则、必须包含的要求（MonoBehaviour、在 OnDestroy() 中调用 DestroyAd()、展示路径中的广告位频次限制检查（使用广告位时）、取消事件订阅、空值检查、错误处理），以及底价接入示例。将这些模式应用到所有广告实现中。

实现检查点：

“在提供广告实现代码之前，请确认：

• 你是否已在第 7 步完成 SDK 初始化？
• 你是否在 Unity 控制台中看到了 ‘LevelPlay SDK initialized successfully’ 日志消息？

请先确认初始化正常运行，再继续实现广告单元。”

如果用户回答“否”或不确定： 引导其返回第 7 步，在确认初始化正常运行之前，不要提供广告实现代码。

广告格式检查点——生成任何代码前先询问：“你想实现哪些广告格式？激励广告、插屏广告、横幅广告，还是组合使用？”只实现用户选择的格式。之后可以通过“Adding More Ad Formats Later”一节添加更多格式。

首先询问用户希望如何组织广告代码。在用户回答之前，不要生成任何代码：

“你希望如何组织广告实现代码？”

1. 为每种广告格式分别创建管理器脚本 - 创建独立脚本，例如 RewardedAdManager.cs、InterstitialAdManager.cs、BannerAdManager.cs（适合较大型项目，职责划分清晰）

2. 使用一个统一的 AdManager 脚本 - 创建一个处理所有广告格式的 AdManager.cs（更简单，所有内容都集中在一处）

3. 只给我代码片段 - 提供实现代码，但不将其封装到特定文件中，以便你按偏好的方式集成

4. 我已经有广告管理器代码 — 检查并帮助修复或更新现有实现

根据用户的回答调整你的回复（请参阅 references/best-practices.md 中的代码生成指南）。

如果用户已经有广告代码（例如，现有的管理器脚本），请先让他们提供代码，然后再生成任何代码 — 这样你就能针对性地修复问题，而不是从头编写新代码。无论他们选择了哪个组织方式选项，这条规则都适用（选项 4 专门用于检查现有代码，但只要用户提到自己已有代码，都应先让他们提供代码）。

然后介绍可选的底价功能（选项 4 除外 — 选项 4 应改为检查现有代码）：

仅针对用户在本次会话中要实现的广告格式，介绍底价范围。参考起始范围：激励广告：$0.50–$2.00 | 插屏广告：$0.20–$1.00 | 横幅广告：$0.05–$0.20。只包含正在实现的格式对应的范围。

"可选 — 高级：底价

大多数发布商一开始会跳过此功能，等获取实际的仪表板数据后再添加。你可以放心跳过，之后再回来设置。

如果你想现在设置底价：底价为每个广告单元设置最低出价（USD）—— 它能提高平均 eCPM，但会降低填充率。起始范围： [正在实现的格式对应的范围]

按格式回复数值，或直接回复“跳过”——你随时可以添加底价。"

按格式记录回答。 对提供了数值的格式，在广告构造中接入 Config.Builder().SetBidFloor(...)；标记为“跳过”的格式则使用基本构造函数（请参阅 references/best-practices.md 中的底价示例）。

如果他们选择了选项 4（现有代码）：

• 询问：“请分享你现有的广告管理器代码，以便我们检查”，然后等待对方提供代码。
• 分析实现：检查是否使用当前的 LevelPlay Ad Unit API（LevelPlayRewardedAd、LevelPlayInterstitialAd、LevelPlayBannerAd），是否使用了已弃用的 IronSource.Agent API，回调注册和取消订阅是否正确，以及是否缺少错误处理或存在内存泄漏。
• 提供具体指导：
  • 如果使用了已弃用的 API：“你正在使用旧的 IronSource.Agent API。以下是迁移到新的 LevelPlay Ad Unit API 的方法：”（完整迁移详情见 references/migration-sdk-9.md — 初始化请参阅场景 B，各广告格式请参阅场景 C，包括 C5 完整性检查清单）
  • 如果使用的是当前 API 但存在问题：“你的实现整体不错，但我发现了[具体问题]。以下是修复方法：”
  • 如果实现正确：“你的实现很完善。你还想添加哪些广告格式？”
• 以代码片段的形式提供修复方案，或建议重构。检查完成后添加新格式时，只针对这些新格式提供底价提示，确认是沿用现有组织方式还是采用新的组织方式，然后遵循选项 1–3 中的相同指南。

每种广告格式都应遵循详细参考文档中的实现指南：

• 激励广告：参阅 references/rewarded-api.md
• 插屏广告：参阅 references/interstitial-api.md
• 横幅广告：参阅 references/banner-api.md

**展示级收入跟踪（因版本而异）：**参阅 references/ilrd-api.md，将展示数据转发到分析平台（Firebase、AppsFlyer、Adjust、Singular 或自定义后端）。

• **SDK 9.5.0+（当前版本）：**创建每个广告对象后，立即订阅其 OnAdImpressionDataReady 事件（并在 OnDestroy() 中取消订阅）。生成的每个广告管理器都要添加此代码 — 这是 SDK 9.5.0+ 中正确的 ILRD 路径。
• SDK 9.4.x 及更早版本：ILRD 使用单个全局 LevelPlay.OnImpressionDataReady 事件，并在初始化脚本中接入（步骤 7）。如果用户在步骤 7 中回答“是”或“不确定”，则该事件已接入。如果用户回答“否”且现在希望添加，则需在现有的 LevelPlay.Init() 调用之前订阅 LevelPlay.OnImpressionDataReady。

10. 测试与验证

LevelPlay 为开发的不同阶段提供了两种验证方式。完整详情——包括设置、回调行为表、Test Suite 初始化器模板，以及 iOS 协程的放置位置——请参阅 references/testing-and-validation.md。用户进行测试时，请阅读该文档。

早期开发：Unity Editor 中的模拟广告。 适用于快速迭代和回调测试。在 Editor 中按下 Play 会自动提供模拟广告——但仅当当前构建目标为 Android 或 iOS 时（Standalone/PC/Mac 不会返回广告；这是“Editor 中没有广告”最常见的原因——请参阅步骤 4）。模拟广告可使用任意 App Key/Ad Unit ID，但建议使用真实凭据，以免之后忘记更换。模拟广告会触发大多数回调（OnAdLoaded/Displayed/Rewarded/Closed），但不会触发失败、点击或展示/ILRD 回调——因此，请在设备上测试错误处理。详情和完整的回调表请参阅 references/testing-and-validation.md。

集成验证：LevelPlay Test Suite（推荐）。 在设备上针对真实广告网络进行全面验证的首选方式。必须遵守以下规则，不可更改：

• LevelPlay.SetMetaData("is_test_suite", "enable"); 必须在 LevelPlay.Init() 之前
• LevelPlay.LaunchTestSuite(); 必须放在 OnInitSuccess 内
• 需要设备构建（在 Editor 中无法运行）；启用 Development Build，以便查看 SDK 日志；使用生产环境的 App Key。
• 正式发布前移除这两行。
• iOS 协程初始化器：将 SetMetaData 放在 InitializeLevelPlay() 内的第一行、Init 之前（不要放在 Start() 中）。

将这两行添加到现有的 LevelPlayInitializer.cs 中（不要新建文件）。完整设置、适用于没有初始化器的用户的独立模板，以及测试工作流均见 references/testing-and-validation.md。

生产发布检查清单

正式发布前：

• 已在设备上成功完成 Test Suite 验证
• 所有广告格式均能正确加载（Rewarded、Interstitial，以及已实现的 Banner）
• 所有回调均按预期触发
• 已确认 App Key 和广告单元 ID 均为正确的生产环境配置
• 已在多台设备上测试（不同屏幕尺寸、OS 版本）
• 已完成 iOS 特定要求（如果目标平台为 iOS）：
  • 已在 Info.plist 中配置 SKAdNetwork ID（见 references/ios-setup.md）
  • 已实现 App Tracking Transparency（ATT）框架（见 references/ios-setup.md）
  • 如有需要，已配置 iOS 隐私清单
  • 已在实体 iOS 设备上测试（不只是模拟器）
• 已完成 Android 特定要求（如果目标平台为 Android）：
  • 已解决 Google Play Services 依赖项（已完成步骤 4）
  • 如果目标 API 为 33+，已将 AD_ID 权限添加到 AndroidManifest.xml（见步骤 4）
  • 已在实体 Android 设备上测试
• 已在生产环境中使用真实广告进行测试
• 已实现广告频次上限（如果使用插屏广告）
• 错误处理正常工作（通过飞行模式测试——广告应能正常失败，不会导致崩溃或阻塞游戏）

稍后添加更多广告格式

如果你已经集成了一些广告格式，并想添加更多格式：

1. 跳至步骤 9——无需重复初始设置步骤。继续之前，请查看 Unity 控制台，确认其中有“LevelPlay SDK initialized successfully”日志，以验证现有初始化仍正常工作。
2. 选择要实现的其他广告格式
3. 遵循之前使用的相同组织模式：
   • 如果你创建了单独的管理器脚本，请为新格式创建一个新的管理器脚本
   • 如果你使用了统一的 AdManager，请将新格式的代码添加到现有的 AdManager 类中
   • 如果你使用了代码片段，请按照相同模式集成新的代码片段
4. 遵循步骤 9 中的相同实现指南，以实现新的广告格式
5. 按照步骤 10 中的测试指南测试新格式

示例：如果你最初只使用单独的管理器脚本实现了激励广告，现在想添加插屏广告：请按照 RewardedAdManager.cs 的相同结构创建 InterstitialAdManager.cs，遵循 references/interstitial-api.md 中的插屏广告指南，并在编辑器和设备上进行测试。添加新格式的同时，现有广告格式会继续正常工作。

最佳实践

实现广告代码之前，请阅读 references/best-practices.md。其中介绍了加载策略（按格式区分）、展示位置策略、错误处理和优雅降级、内存管理、频次管理，以及需要避免的常见错误——请将这些模式应用到所有广告实现中。

常见问题与解决方案

如果用户报告问题，请将其引导至 references/troubleshooting.md 中对应的问题并遵循其中的说明（如果其中的指南要求停止生成代码，则应停止）。不要等用户打开参考文档——直接提供解决方法。如果用户尚未开始集成，请从步骤 1 开始。

症状	可能的根本原因	操作
Unity.Services.LevelPlay 出现 CS0246；所有 LevelPlay 代码下方都显示红色波浪线	未安装 Ads Mediation 包	停止提供代码；检查 Packages/packages-lock.json 中是否有 com.unity.services.levelplay；安装（步骤 3）；重启编辑器；然后继续。请参阅 troubleshooting.md。
Android gradle / iOS 构建因依赖项错误而失败；在编辑器中可编译，但构建时失败	原生依赖项尚未解析	解析依赖项（步骤 4 / dependency-resolution.md）；确认 Assets/Plugins/Android/；重新构建。请参阅 troubleshooting.md。
广告未加载	SDK 未初始化、App Key 错误、在初始化前创建了广告，或网络连接不可用	确认在创建广告前触发了 OnInitSuccess；检查 App Key；在设备上测试。请参阅 troubleshooting.md。
回调未触发	在初始化后注册事件、缺少订阅，或脚本已销毁	在 Init() 前注册回调；验证订阅；使用持久化的 GameObject。请参阅 troubleshooting.md。
特定平台的构建错误（iOS SKAdNetwork/ATT/frameworks；Android Play Services/manifest/gradle）	平台设置不完整	请参阅 troubleshooting.md 和 references/ios-setup.md。
Android 构建在解析来自 android-sdk.is.com 的 com.ironsource.sdk 依赖项时失败（之前正常工作；没有任何改动）	依赖项已迁移至 Maven Central；旧的 is.com 仓库已关闭	按照 references/migration-sdk-9.md 中的场景 D 操作：删除过时的依赖项 XML 文件，通过 Network Manager 重新安装，并确认不再包含 is.com 引用。

何时阅读详细参考文档

根据用户正在进行的操作阅读相应参考文档：

• references/dependency-resolution.md：解决原生依赖问题（步骤 4），或处理 gradle/CocoaPods 构建失败
• references/initialization-api.md：步骤 7 的初始化代码组织选项和 ILRD 初始化接线；以及用户 ID、细分、同意管理和高级配置
• references/privacy-settings.md：GDPR、CCPA 或 COPPA 合规（包括旧版 SetConsent 和完整的网络键列表）
• references/ios-setup.md：iOS 构建——ATT、SKAdNetwork、iOS 协程初始化器
• references/rewarded-api.md / references/interstitial-api.md / references/banner-api.md：实现各广告格式（步骤 9）
• references/best-practices.md：策略详情（步骤 8）、步骤 9 的代码生成指南、优化和广告位
• references/ilrd-api.md：将 ILRD 接入分析平台
• references/testing-and-validation.md：模拟广告和测试套件（步骤 10）
• references/troubleshooting.md：编译/构建错误、广告无法加载、回调未触发
• references/migration-sdk-9.md：从 IronSource 或较旧的 LevelPlay API 迁移、将 SDK 升级到 9.x.x、从 Unity Ads 迁移，或 Maven Central 依赖项构建失败（步骤 0）

示例

注意：示例展示了经过简化的工作流，仅供说明。实际操作中，请按顺序完成步骤 1–10。

以收入为目标的游戏（“在我的休闲益智游戏中最大化广告收入”）：步骤 1–7，用于确认环境/目标/安装/依赖项/App Key/AdMob/初始化 → 步骤 8 推荐收入策略 → 步骤 9 询问代码组织方式并生成所选结构 → 步骤 10 测试。

以用户体验为目标的游戏（“提供可选的激励广告以获得额外生命，但不要惹恼玩家”）：流程相同，但步骤 8 推荐用户体验策略（仅激励广告，由用户主动触发），步骤 9 按照正确模式实现激励广告。

现有项目（“已有 GameManager，在关卡之间添加插屏广告”）：流程相同，步骤 8 选择均衡策略，步骤 9 询问查看 GameManager.cs，然后提供选项 2 的代码片段。

核心规则（提醒）

以下规则与本文件顶部的规则相同——它们是最重要的护栏，在此重述，以便在漫长的工作流结束时仍清晰可见：

• 根据实际项目进行编辑器端检查，而非依赖假设——读取项目文件，或请用户在 Editor 中确认。本技能生成的 C# 脚本是供用户保存到项目中的 MonoBehaviour 文件，不用于内联执行。
• 本技能仅涵盖 LevelPlay 集成路径，不涵盖其他中介 SDK。如果用户明确询问替代方案，应说明存在其他方案，并引导他们查阅相应供应商自己的文档——不要描述、评价或对竞品产品作出任何断言。
• 按照本技能中说明的步骤操作，只提供其中描述的文件和配置。不要主动添加步骤、创建文件或根据常识提出建议。如果用户询问的问题超出本技能范围，应先检查技能和参考文件，确认其中未涵盖该问题。如果确实未涵盖，则运用常识作答，但不要因此在集成工作流中加入额外步骤或文件。
• 按顺序逐步执行集成工作流。每次只询问当前步骤所需的问题——不要提前收集后续步骤的信息。每个检查点都要等待用户回复后再继续。
• 如果某个步骤指向参考文件，应阅读该文件并使用其中的内容——不要用常识替代。必须严格按照原文给出 4 种初始化选项（步骤 7）和 4 种代码组织选项（步骤 9），并逐字询问 ILRD 问题（步骤 7）。