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

• Core Adapty：这是 Adapty 在您的应用中正常运行所必需的核心 SDK。
• AdaptyUI：如果您使用 Adapty 付费墙编辑工具（一款无需编写代码即可轻松创建跨平台付费墙的用户友好型工具），则需要此可选模块。

环境要求

Adapty SDK 支持 iOS 13.0+，但需要 iOS 15.0+ 才能与付费墙编辑工具中创建的付费墙配合使用。

安装 Adapty SDK

1. 从 GitHub 下载 adapty-unity-plugin-*.unitypackage 并将其导入您的项目。

2. 下载并导入 External Dependency Manager 插件。

3. SDK 使用”External Dependency Manager”插件来处理 iOS Cocoapods 依赖项和 Android gradle 依赖项。安装完成后，您可能需要手动调用依赖管理器：

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

   以及

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

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

激活 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" 替换为您的密钥。

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 尽早完成初始化。

将 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**
   }

现在在您的应用中设置付费墙：

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

激活 Adapty SDK 的 AdaptyUI 模块

如果您计划使用付费墙编辑工具并已安装 AdaptyUI 模块，则需要激活 AdaptyUI。您可以在配置过程中激活它：

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

可选设置

日志记录

设置日志系统

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

级别	描述
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 Tracking Transparency 提示，或在您的应用不需要基于广告 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);

故障排查

Android 备份规则（自动备份配置）

部分 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" />