安装与配置 Android SDK

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

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

系统要求

最低 SDK 要求：minSdkVersion 21

安装 Adapty SDK

选择您的依赖项配置方式：

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

dependencies {
    ...
    implementation platform('io.adapty:adapty-bom:<the latest SDK version>')
    implementation 'io.adapty:android-sdk'
    
    // Only add this line if you plan to use Paywall Builder
    implementation 'io.adapty:android-ui'
}

dependencies {
    ...
    implementation(platform("io.adapty:adapty-bom:<the latest SDK version>"))
    implementation("io.adapty:android-sdk")
    
    // Only add this line if you plan to use Paywall Builder:
    implementation("io.adapty:android-ui")
}

//libs.versions.toml

[versions]
..
adaptyBom = "<the latest SDK version>"

[libraries]
..
adapty-bom = { module = "io.adapty:adapty-bom", version.ref = "adaptyBom" }
adapty = { module = "io.adapty:android-sdk" }

// Only add this line if you plan to use Paywall Builder:
adapty-ui = { module = "io.adapty:android-ui" }

//module-level build.gradle.kts

dependencies {
    ...
    implementation(platform(libs.adapty.bom))
    implementation(libs.adapty)
    
    // Only add this line if you plan to use Paywall Builder:
    implementation(libs.adapty.ui)
}

如果依赖项无法解析，请确认您的 Gradle 脚本中包含 mavenCentral()。

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

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

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

// In your Application class
import android.app.Application
import com.adapty.Adapty
import com.adapty.models.AdaptyConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Adapty.activate(
            applicationContext,
            AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        )
    }
}

// In your Application class
import android.app.Application;
import com.adapty.Adapty;
import com.adapty.models.AdaptyConfig;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Adapty.activate(
            getApplicationContext(),
            new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        );
    }
}

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

• 如果您使用 Adapty 付费墙编辑工具，请参阅付费墙编辑工具快速入门。
• 如果您自行构建付费墙 UI，请参阅自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

如果您计划使用付费墙编辑工具，则需要 AdaptyUI 模块。当您激活核心模块时，它会自动激活，无需执行任何其他操作。

配置 Proguard

在将应用发布到生产环境之前，请将 -keep class com.adapty.** { *; } 添加到您的 Proguard 配置中。

可选配置

日志

设置日志系统

Adapty 会记录错误和其他重要信息，帮助您了解系统运行状态。以下日志级别可供选择：

您可以在配置 Adapty 之前在应用中设置日志级别。

import com.adapty.Adapty
import com.adapty.utils.AdaptyLogLevel

Adapty.logLevel = AdaptyLogLevel.VERBOSE 
//recommended for development and the first production release

import com.adapty.Adapty;
import com.adapty.utils.AdaptyLogLevel;

Adapty.setLogLevel(AdaptyLogLevel.VERBOSE);
//recommended for development and the first production release

重定向日志系统消息

如果您出于某种原因需要将 Adapty 的消息发送到您的系统或保存到文件中，可以覆盖默认行为：

import com.adapty.Adapty
import com.adapty.utils.AdaptyLogLevel

Adapty.setLogHandler { level, message ->
    //handle the log
}

import com.adapty.Adapty;
import com.adapty.utils.AdaptyLogLevel;

Adapty.setLogHandler((level, message) -> {
    //handle the log
});

数据策略

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

禁用 IP 地址收集与共享

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

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

import com.adapty.models.AdaptyConfig

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build()

import com.adapty.models.AdaptyConfig;

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build();

禁用广告 ID（Ad ID）收集与共享

在激活 Adapty 模块时，将 adIdCollectionDisabled 设置为 true 可禁用用户广告 ID 的收集。默认值为 false。

使用此参数可遵守 Play Store 政策、避免触发广告 ID 权限提示，或当您的应用不需要基于 Ad ID 的广告归因或数据分析时使用。

import com.adapty.models.AdaptyConfig

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build()

import com.adapty.models.AdaptyConfig;

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build();

为 AdaptyUI 设置媒体缓存配置

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

使用 AdaptyUI.configureMediaCache 可覆盖默认缓存大小和有效期。此配置为可选项——如果您不调用此方法，将使用默认值（磁盘大小 100MB，有效期 7 天）。

import com.adapty.ui.AdaptyUI
import com.adapty.ui.AdaptyUI.MediaCacheConfiguration
import com.adapty.utils.days

val cacheConfig = MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(3.days)
    .build()

AdaptyUI.configureMediaCache(cacheConfig)

import com.adapty.ui.AdaptyUI;
import com.adapty.ui.AdaptyUI.MediaCacheConfiguration;
import com.adapty.utils.TimeInterval;

MediaCacheConfiguration cacheConfig = new MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(TimeInterval.days(3))
    .build();

AdaptyUI.configureMediaCache(cacheConfig);

参数：

设置混淆账户 ID

Google Play 在某些使用场景下需要混淆账户 ID，以增强用户隐私和安全性。这些 ID 可帮助 Google Play 识别购买行为，同时保持用户信息匿名，对于防欺诈和数据分析尤为重要。

如果您的应用处理敏感用户数据，或需要遵守特定隐私法规，则可能需要设置这些 ID。混淆 ID 使 Google Play 能够在不暴露实际用户标识符的情况下追踪购买行为。

import com.adapty.models.AdaptyConfig

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build()

import com.adapty.models.AdaptyConfig;

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build();

在自定义进程中运行 Adapty

默认情况下，Adapty 只能在您应用的主进程中运行。 如果您的应用使用多个进程，请只初始化 Adapty 一次，否则可能会出现意外行为。

如果您需要在不同进程中运行 Adapty，请在配置中指定：

import com.adapty.models.AdaptyConfig

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build()

import com.adapty.models.AdaptyConfig;

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build();

如果您尝试在未设置此值的情况下在其他进程中激活 Adapty，SDK 将记录一条警告并跳过激活。

启用本地访问等级

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

import com.adapty.models.AdaptyConfig

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(true)
    .build()

import com.adapty.models.AdaptyConfig;

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(true)
    .build();

故障排查

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

某些 SDK（包括 Adapty）会附带自己的 Android 自动备份配置。如果您同时使用多个定义了备份规则的 SDK，Android 清单合并器可能会失败，并出现涉及 android:fullBackupContent、android:dataExtractionRules 或 android:allowBackup 的错误。

典型错误症状：Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/sample_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

要解决此问题，您需要：

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

• 将 Adapty 和其他 SDK 的备份规则合并到单个 XML 文件中（Android 12+ 需要一对文件）。

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

如果尚未添加，请在根 <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. 创建合并后的备份规则文件

在 app/src/main/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"/>

    
    
</full-backup-content>

完成此设置后：

• Adapty 的备份排除项（AdaptySDKPrefs.xml）得到保留。

• 其他 SDK 的排除项（例如 appsflyer-data）也会生效。

• 清单合并器使用您应用的配置，不再因备份属性冲突而失败。

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

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

为确保购买正常进行，启动购买流程的 Activity 只能使用 standard 或 singleTop 启动模式，避免使用其他任何模式。

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

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