安装与配置 Adapty Kotlin Multiplatform SDK

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

• 核心 Adapty：此基础 SDK 是 Adapty 在您的应用中正常运行所必需的。
• 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 代码中进行。

import com.adapty.kmp.Adapty

import com.adapty.kmp.models.AdaptyConfig

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)。

import com.adapty.kmp.Adapty

import com.adapty.kmp.models.AdaptyConfig
import com.adapty.kmp.models.AdaptyLogLevel

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 会记录错误和其他重要信息，帮助您了解正在发生的情况。以下是可用的日志级别：

import com.adapty.kmp.models.AdaptyConfig

import com.adapty.kmp.models.AdaptyLogLevel

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

数据政策

禁用 IP 地址收集与共享

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

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

import com.adapty.kmp.models.AdaptyConfig

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 的广告归因或分析时使用。

import com.adapty.kmp.models.AdaptyConfig

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

为 AdaptyUI 设置媒体缓存配置

默认情况下，AdaptyUI 会缓存媒体（如图片和视频）以提高性能并减少网络使用量。您可以通过提供自定义配置来定制缓存设置。

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

import com.adapty.kmp.models.AdaptyConfig

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：

import com.adapty.kmp.models.AdaptyConfig

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

备份恢复时清除数据

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

import com.adapty.kmp.models.AdaptyConfig

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