Adapty SDK 包含两个核心模块，可无缝集成到您的 Unity 应用中：

• Core Adapty：这是必要的 SDK，Adapty 在您的应用中正常运行需要它。
• AdaptyUI：此模块用于渲染流程，以及旧版编辑工具的付费墙。

系统要求

Adapty SDK 支持 iOS 13.0+，但使用付费墙编辑工具创建的付费墙需要 iOS 15.0+。Adapty SDK 4.1（新增对流程的支持）要求整个应用的最低部署目标为 iOS 15.0+：若部署目标低于此版本，Unity Editor 中的构建验证器将阻止 iOS 构建。使用 SDK 4.x 构建 iOS 应用还需要 Xcode 26 或更高版本——其作为 Swift Package 引入的原生 iOS SDK 使用 Swift tools 6.2 构建。

依赖项

Adapty SDK 在 Android 上支持以下 Google Play Billing Library 版本：

Adapty SDK 版本	Billing Library 版本
3.17.0 及更高版本	v8
3.15.0–3.15.2	默认为 v7，若其他依赖项将其升级则使用 v8

安装 Adapty SDK

我们始终建议安装最新版本的 SDK——它包含最新的稳定性修复和改进。

选择你偏好的安装方式：

安装 SDK 后，请完成以下步骤：

1. 安装 External Dependency Manager (EDM) 插件。Adapty SDK 使用它来处理 iOS 依赖项和 Android gradle 依赖项。

2. 安装 EDM 后，您可能需要调用依赖管理器：

   Assets -> External Dependency Manager -> Android Resolver -> Force Resolve

   以及

   Assets -> External Dependency Manager -> iOS Resolver -> Install Cocoapods

3. 在为 iOS 构建 Unity 项目时，您会得到 Unity-iPhone.xcworkspace 文件，您必须打开该文件而非 Unity-iPhone.xcodeproj，否则 Cocoapods 依赖项将不会被使用。

Adapty SDK 4.1

SDK 4.1 — 新增了对流程的支持 — 是 4.x 系列的首个稳定版本。要通过 Unity Package Manager 安装，请在 Git URL 后附加版本标签：

https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.1.0

如果通过 Unity 包安装，请从 4.1.0 release 下载 adapty-unity-plugin-4.1.0.unitypackage。

Two build-setup changes come with 4.x — the native iOS Adapty SDK is declared as a remote Swift package and no longer installs through CocoaPods:

• 将 External Dependency Manager 更新至 1.2.188 或更高版本 — 旧版本不支持 Swift Package Manager 依赖项。这是 SDK 4.1 声明的对等依赖版本，如果你的项目使用了更旧的版本，Unity 会发出警告。
• 上述 CocoaPods 步骤（iOS Resolver -> Install Cocoapods，打开 Unity-iPhone.xcworkspace）仅适用于 SDK 3.x。在 SDK 4.1 中，EDM 会自动将 Swift 包添加到生成的 Xcode 项目中。
• 将 iOS 部署目标设置为 15.0 或更高版本。Unity Editor 中的构建验证器会在不满足此条件时阻止 iOS 构建。

有关 4.x 版本的完整变更列表，请参阅迁移指南。

激活 Adapty SDK 的 Adapty 模块

在你的应用代码中激活 Adapty SDK。

获取您的 Public SDK Key：

1. 打开 Adapty 看板，导航至 App settings → General。
2. 在 Api keys 部分，复制 Public SDK Key（不是 Secret Key）。
3. 将代码中的 "YOUR_PUBLIC_SDK_KEY" 替换为实际值。

或者，使用 Adapty CLI 以编程方式获取：

npm install -g adapty
adapty auth login
adapty apps list

或者，直接运行：

npx adapty auth login
adapty apps list

• 请确保使用 Public SDK key 初始化 Adapty，Secret key 仅用于服务端 API。
• SDK keys 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的那个。

using UnityEngine;
using AdaptySDK;

public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
    void Start() {
        DontDestroyOnLoad(this.gameObject);
        Adapty.SetEventListener(this);

        var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY");

        Adapty.Activate(builder.Build(), (error) => {
            if (error != null) {
                // handle the error
                return;
            }
        });
    }

    public void OnLoadLatestProfile(AdaptyProfile profile) { }
    public void OnInstallationDetailsSuccess(AdaptyInstallationDetails details) { }
    public void OnInstallationDetailsFail(AdaptyError error) { }
}

设置事件监听

创建一个脚本来监听 Adapty 事件，在场景中将其命名为 AdaptyListener。建议对该对象使用 DontDestroyOnLoad 方法，确保它在应用程序的整个生命周期内持续存在。

Adapty 使用 AdaptySDK 命名空间。在使用 Adapty SDK 的脚本文件顶部，你可以添加：

using AdaptySDK;

订阅 Adapty 事件：

using UnityEngine;
using AdaptySDK;

public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
    public void OnLoadLatestProfile(AdaptyProfile profile) {
        // handle updated profile data
    }

    public void OnInstallationDetailsSuccess(AdaptyInstallationDetails details) { }
    public void OnInstallationDetailsFail(AdaptyError error) { }
}

我们建议调整脚本执行顺序，将 AdaptyListener 放在 Default Time 之前，以确保 Adapty 尽早完成初始化。

接下来，在应用中配置付费墙：

• 如果您使用流程与付费墙编辑工具，请先激活 AdaptyUI 模块，然后按照快速入门指南操作。
• 如果您自行构建付费墙 UI，请参阅自定义付费墙快速入门指南。

激活 Adapty SDK 的 AdaptyUI 模块

如果你计划使用 Flow & 付费墙编辑工具 并已安装 AdaptyUI 模块，则需要激活 AdaptyUI。你可以在配置时进行激活：

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetActivateUI(true);

可选设置

日志记录

配置日志系统

Adapty 会记录错误和其他重要信息，帮助你了解运行情况。以下是可用的日志级别：

Level	Description
error	仅记录错误日志
warn	记录错误以及 SDK 中不会导致严重错误但值得关注的消息
info	记录错误、警告及各类信息消息
verbose	记录所有可能在调试时有用的附加信息，例如函数调用、API 请求等

你可以在配置 Adapty 时设置应用的日志级别：

// 'verbose' is recommended for development and the first production release
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY");
builder.LogLevel = AdaptyLogLevel.Verbose;

你也可以在运行时动态修改日志级别：

Adapty.SetLogLevel(AdaptyLogLevel.Verbose, (error) => {
    // handle result
});

数据政策

Adapty 不会存储用户的个人数据，除非您明确发送，但您可以实施额外的数据安全策略，以符合应用商店或所在国家/地区的法规要求。

禁用 IP 地址采集与共享

在激活 Adapty 模块时，将 SetIPAddressCollectionDisabled 设置为 true 即可禁用用户 IP 地址的采集与共享。默认值为 false。

使用此参数可增强用户隐私保护、遵守地区性数据保护法规（如 GDPR 或 CCPA），或在应用不需要基于 IP 的功能时减少不必要的数据采集。

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetIPAddressCollectionDisabled(true);

禁止采集和共享广告 ID

在激活 Adapty 模块时，将 SetAppleIDFACollectionDisabled 和/或 SetGoogleAdvertisingIdCollectionDisabled 设置为 true 可禁用广告标识符的收集。默认值为 false。

如需遵守 App Store/Google Play 政策、避免触发 App 跟踪透明度提示，或者你的应用不需要基于广告 ID 的广告归因或分析功能，可使用此参数。

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAppleIDFACollectionDisabled(true)
    .SetGoogleAdvertisingIdCollectionDisabled(true);

为 AdaptyUI 配置媒体缓存

默认情况下，AdaptyUI 会缓存媒体内容（如图片和视频），以提升性能并减少网络流量。你可以通过提供自定义配置来调整缓存设置。

使用 SetAdaptyUIMediaCache 覆盖默认缓存设置：

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyUIMediaCache(
        100 * 1024 * 1024, // MemoryStorageTotalCostLimit 100MB
        null, // MemoryStorageCountLimit
        100 * 1024 * 1024 // DiskStorageSizeLimit 100MB
    );

参数：

参数	是否必填	描述
memoryStorageTotalCostLimit	可选	内存缓存大小（字节）。默认值因平台而异。
memoryStorageCountLimit	可选	内存存储的条目数量上限。默认值因平台而异。
diskStorageSizeLimit	可选	磁盘文件大小上限（字节）。默认值因平台而异。

启用本地访问等级（Android）

默认情况下，本地访问等级在 iOS 上已启用，在 Android 上已禁用。若要在 Android 上同样启用，请将 SetGoogleLocalAccessLevelAllowed 设置为 true：

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetGoogleLocalAccessLevelAllowed(true);

备份恢复时清除数据

当 SetAppleClearDataOnBackup 设置为 true 时，SDK 会检测应用从 iCloud 备份恢复的情况，并删除所有本地存储的 SDK 数据，包括已缓存的用户画像信息、产品详情和付费墙。之后 SDK 将以全新状态完成初始化。默认值为 false。

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAppleClearDataOnBackup(true);

启用 Adapty 归因

如果您使用 Adapty 归因，请在激活 SDK 时将 SetAdaptyAttributionEnabled 设置为 true。默认值为 false：不设置此参数时，SDK 不会注册安装或向您的应用传递安装详情。在低于 4.1 的 SDK 版本中，Adapty 归因会自动启用。

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyAttributionEnabled(true);

故障排查

Android 备份规则（Auto Backup 配置）

部分 SDK（包括 Adapty）会附带自己的 Android Auto Backup 配置。如果您使用了多个定义备份规则的 SDK，Android 清单合并器可能会报错，错误信息中通常包含 android:fullBackupContent、android:dataExtractionRules 或 android:allowBackup。

常见错误提示：Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

要解决此问题，您需要：

• 告知清单合并器使用您应用中的备份相关属性值。

• 创建备份规则文件，将 Adapty 的规则与其他 SDK 的规则合并。

1. 在清单文件中添加 tools 命名空间

在 AndroidManifest.xml 文件中，确保根标签 <manifest> 包含 tools：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. 在 <application> 中覆盖备份属性

在同一个 AndroidManifest.xml 文件中，更新 <application> 标签，使您的应用提供最终属性值，并通知清单合并器替换库中的属性值：

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

如果某个 SDK 也设置了 android:allowBackup，请将其一并加入 tools:replace：

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. 创建合并后的备份规则文件

在 Android 项目的 res/xml/ 目录中创建 XML 文件，将 Adapty 的规则与其他 SDK 的规则合并。由于 Android 在不同系统版本中使用不同的备份规则格式，同时创建两个文件可确保您的应用在所有支持的 Android 版本上都能正常运行。

适用于 Android 12 及更高版本（使用新的数据提取规则格式）：

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

适用于 Android 11 及更低版本（使用旧版完整备份内容格式）：

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

Android 中从其他应用返回后购买失败

如果启动购买流程的 Activity 使用了非默认的 launchMode，当用户从 Google Play、银行应用或浏览器返回时，Android 可能会以错误的方式重建或复用该 Activity。这会导致购买结果丢失或被当作已取消处理。

为确保购买流程正常运行，请仅将启动购买流程的 Activity 的启动模式设置为 standard 或 singleTop，避免使用其他任何模式。

在 AndroidManifest.xml 中，确保启动购买流程的 Activity 设置为 standard 或 singleTop：

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />

Android 上显示付费墙时应用崩溃

如果应用在 Android 上显示付费墙时崩溃，可能是因为 Gradle 配置中缺少 Kotlin 插件。添加方法如下：

1. 在 Player Settings 中，确保已勾选 Custom Launcher Gradle Template 和 Custom Base Gradle Template 选项。

   

2. 将以下内容添加到 /Assets/Plugins/Android/launcherTemplate.gradle：

   apply plugin: 'com.android.application'
   apply plugin: 'kotlin-android'
   apply from: 'setupSymbols.gradle'
   apply from: '../shared/keepUnitySymbols.gradle'

3. 将以下内容添加到 /Assets/Plugins/Android/baseProjectTemplate.gradle：

   plugins {
       // If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity
       // See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html
       // See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
       // To specify a custom Gradle version in Unity, go do "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version
       id 'com.android.application' version '8.3.0' apply false
       id 'com.android.library' version '8.3.0' apply false
       id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
       **BUILD_SCRIPT_DEPS**
   }