安装并配置 Adapty Kotlin Multiplatform SDK

Adapty SDK 包含两个关键模块，可无缝集成到您的移动应用中：

• 核心 Adapty：这是 Adapty 正常运行所必需的基础 SDK。
• AdaptyUI (io.adapty:adapty-kmp-ui)：如果你使用 Adapty 付费墙编辑工具 并搭配 Compose Multiplatform 渲染层（view.present()），则需要此模块。如果你的项目不使用 Compose Multiplatform，可以改用核心模块中的 createNativePaywallView 和 createNativeOnboardingView。

如需完整的实现步骤演示，也可以参考以下视频：

要求

Adapty Kotlin Multiplatform SDK 兼容 Xcode 16.2 及更高版本。

通过 Gradle 安装 Adapty SDK

无论是 Android 还是 iOS 应用，都需要通过 Gradle 安装 Adapty SDK。

选择你的依赖配置方式：

• 标准 Gradle：将依赖添加到模块级 build.gradle
• 如果项目使用 .gradle.kts 文件，将依赖添加到模块级 build.gradle.kts
• 如果使用版本目录，将依赖添加到 libs.versions.toml 文件，然后在 build.gradle.kts 中引用

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation libs.adapty.kmp
            }
        }
    }
}

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.adapty.kmp)
            }
        }
    }
}

// libs.versions.toml
[versions]
..
adapty-kmp    = "<the latest SDK version>"

[libraries]
..
adapty-kmp = { module = "io.adapty:adapty-kmp", version.ref = "adapty-kmp" }

// build.gradle.kts

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.adapty.kmp)
            }
        }
    }
}

allprojects {
    repositories {
        ...
        mavenCentral()
    }
}

dependencyResolutionManagement {
    ...
    repositories {
        ...
        google()
        mavenCentral()
    }
}

激活 Adapty SDK

基本设置

尽早添加初始化代码——通常放在两个平台共用的 Kotlin 代码中。

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .build()

Adapty.activate(configuration = config)
    .onSuccess {
        Log.d("Adapty", "SDK initialised")
    }
    .onError { error ->
        Log.e("Adapty", "Adapty init error: ${error.message}")
    }

获取 Public SDK Key 的步骤：

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

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

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

激活 Adapty SDK 的 AdaptyUI 模块

如果你计划激活 AdaptyUI 模块以使用 Adapty 付费墙编辑工具，请确保在配置中设置 .withActivateUI(true)。

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withActivateUI(true)           // true for activating the AdaptyUI module
    .build()  

Adapty.activate(configuration = config)
    .onSuccess {
        Log.d("Adapty", "SDK initialised")
    }
    .onError { error ->
        Log.e("Adapty", "Adapty init error: ${error.message}")
    }    

配置 Proguard（Android）

在正式发布应用之前，您可能需要在 Proguard 配置中添加 -keep class com.adapty.** { *; }。

可选配置

日志记录

配置日志系统

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

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withLogLevel(AdaptyLogLevel.VERBOSE) // recommended for development
     .build()   

数据策略

禁用 IP 地址的收集与共享

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

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

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withIpAddressCollectionDisabled(true)  
     .build()  

禁用广告 ID 的收集与共享

激活 Adapty 模块时，将 appleIdfaCollectionDisabled（iOS）或 googleAdvertisingIdCollectionDisabled（Android）设置为 true，即可禁用广告标识符的收集。默认值为 false。 使用此参数可满足 App Store/Play Store 的政策要求，避免触发 App Tracking Transparency 提示，或在你的应用不需要基于广告 ID 的广告归因或分析时使用。

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withGoogleAdvertisingIdCollectionDisabled(true)        // Android only
     .withAppleIdfaCollectionDisabled(true)                  // iOS only
     .build()  

为 AdaptyUI 配置媒体缓存

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

使用 mediaCache 覆盖默认缓存配置：

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withMediaCacheConfiguration(
        AdaptyConfig.MediaCacheConfiguration(
            memoryStorageTotalCostLimit = 200 * 1024 * 1024, // 200 MB
            memoryStorageCountLimit = Int.MAX_VALUE,          
            diskStorageSizeLimit = 200 * 1024 * 1024 // 200 MB
        )
    )
    .build()

启用本地访问等级（Android）

默认情况下，Android 的本地访问等级处于禁用状态。要启用它们，请将 withLocalAccessLevelAllowed 设置为 true：

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withGoogleLocalAccessLevelAllowed(true)
    .build()

恢复备份时清除数据

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

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withAppleClearDataOnBackup(true)
    .build()

故障排查

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