安装并配置 Adapty Kotlin Multiplatform SDK

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

• Core Adapty：这是 Adapty 正常运行所必需的核心 SDK。
• AdaptyUI (io.adapty:adapty-kmp-ui)：该模块通过 Compose Multiplatform 渲染层（view.present()）渲染流程和旧版编辑工具付费墙。如果您的项目不使用 Compose Multiplatform，可以改用核心模块中的 createNativePaywallView 和 createNativeOnboardingView。

如需完整的实现演示，也可以观看以下视频：

要求

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

通过 Gradle 安装 Adapty SDK

使用 Gradle 安装 Adapty SDK 对于 Android 和 iOS 应用都是必需的。

选择你的依赖配置方式：

• 标准 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" 替换为你复制的密钥。

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

• 如果您使用 Flow & Paywall Builder，请先激活 AdaptyUI 模块，然后按照快速入门指南操作。
• 如果您自行构建付费墙 UI，请参阅自定义付费墙快速入门指南。

激活 Adapty SDK 的 AdaptyUI 模块

如果你计划激活 AdaptyUI 模块以使用 Flow & 付费墙编辑工具，请确保在配置中设置 .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 会记录错误和其他重要信息，帮助你了解运行状态。以下是可用的日志级别：

您可以在配置 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 跟踪透明度提示，或者当您的应用不需要基于广告 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()

启用 Adapty 归因

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

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withAdaptyAttributionEnabled(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" />