Cài đặt và cấu hình Android SDK

SDK Adapty bao gồm hai module chính để tích hợp liền mạch vào ứng dụng di động của bạn:

• Core Adapty: SDK cốt lõi này bắt buộc phải có để Adapty hoạt động đúng trong ứng dụng của bạn.
• AdaptyUI: Module này cần thiết nếu bạn sử dụng Adapty Paywall Builder, công cụ no-code thân thiện với người dùng để tạo paywall đa nền tảng một cách dễ dàng. AdaptyUI được kích hoạt tự động cùng với module cốt lõi.

Yêu cầu

Yêu cầu SDK tối thiểu: minSdkVersion 21

Cài đặt Adapty SDK

Chọn phương thức thiết lập dependency của bạn:

• Standard Gradle: Thêm dependency vào module-level build.gradle
• Nếu dự án của bạn dùng file .gradle.kts, thêm dependency vào module-level build.gradle.kts
• Nếu bạn dùng version catalogs, thêm dependency vào file libs.versions.toml, sau đó tham chiếu nó trong 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)
}

Nếu dependency không được resolve, hãy đảm bảo rằng bạn có mavenCentral() trong Gradle scripts.

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

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

Kích hoạt module Adapty của Adapty SDK

Thiết lập cơ bản

Kích hoạt SDK trong code của ứng dụng.

Để lấy Public SDK Key:

1. Truy cập Adapty Dashboard và điều hướng đến App settings → General.
2. Trong phần Api keys, sao chép Public SDK Key (KHÔNG phải Secret Key).
3. Thay thế "YOUR_PUBLIC_SDK_KEY" trong code.

Hoặc lấy theo cách lập trình, sử dụng Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Hoặc, trực tiếp:

npx adapty auth login
adapty apps list

• Đảm bảo bạn sử dụng Public SDK key để khởi tạo Adapty, Secret key chỉ nên dùng cho server-side API.
• SDK keys là duy nhất cho mỗi ứng dụng, vì vậy nếu bạn có nhiều ứng dụng, hãy đảm bảo chọn đúng key.

// In your Application class

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

// In your Application class

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

Bây giờ hãy thiết lập paywall trong ứng dụng của bạn:

• Nếu bạn sử dụng Adapty Paywall Builder, hãy làm theo hướng dẫn nhanh về Paywall Builder.
• Nếu bạn tự xây dựng giao diện paywall, hãy xem hướng dẫn nhanh cho paywall tùy chỉnh.

Kích hoạt module AdaptyUI của Adapty SDK

Nếu bạn có kế hoạch sử dụng Paywall Builder, bạn cần module AdaptyUI. Module này được kích hoạt tự động khi bạn kích hoạt module cốt lõi; bạn không cần thực hiện thêm bất cứ điều gì.

Cấu hình Proguard

Trước khi phát hành ứng dụng lên production, hãy thêm -keep class com.adapty.** { *; } vào cấu hình Proguard của bạn.

Thiết lập tùy chọn

Ghi nhật ký

Thiết lập hệ thống ghi nhật ký

Adapty ghi lại các lỗi và thông tin quan trọng để giúp bạn hiểu những gì đang xảy ra. Có các cấp độ sau:

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

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

Chuyển hướng thông báo từ hệ thống ghi log

Nếu vì lý do nào đó bạn cần gửi thông báo từ Adapty sang hệ thống của mình hoặc lưu chúng vào file, bạn có thể ghi đè hành vi mặc định:

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

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

Chính sách dữ liệu

Adapty không lưu trữ dữ liệu cá nhân của người dùng trừ khi bạn chủ động gửi lên, nhưng bạn có thể áp dụng thêm các chính sách bảo mật dữ liệu để tuân thủ hướng dẫn của cửa hàng hoặc quy định của từng quốc gia.

Tắt tính năng thu thập và chia sẻ địa chỉ IP

Khi kích hoạt module Adapty, đặt ipAddressCollectionDisabled thành true để tắt tính năng thu thập và chia sẻ địa chỉ IP của người dùng. Giá trị mặc định là false. Sử dụng tham số này để tăng cường quyền riêng tư của người dùng, tuân thủ các quy định bảo vệ dữ liệu khu vực (như GDPR hoặc CCPA), hoặc giảm thiểu việc thu thập dữ liệu không cần thiết khi các tính năng dựa trên địa chỉ IP không cần thiết cho ứng dụng của bạn.

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

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

Vô hiệu hóa thu thập và chia sẻ advertising ID (Ad ID)

Khi kích hoạt module Adapty, đặt adIdCollectionDisabled thành true để vô hiệu hóa việc thu thập advertising ID của người dùng. Giá trị mặc định là false. Sử dụng tham số này để tuân thủ chính sách Play Store, tránh kích hoạt lời nhắc cấp quyền advertising ID, hoặc nếu ứng dụng của bạn không cần attribution quảng cáo hay analytics dựa trên Ad ID.

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

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

Cấu hình bộ nhớ cache media cho AdaptyUI

Theo mặc định, AdaptyUI lưu cache media (như hình ảnh và video) để cải thiện hiệu suất và giảm lưu lượng mạng. Bạn có thể tùy chỉnh các cài đặt cache bằng cách cung cấp một cấu hình tùy chỉnh. Dùng AdaptyUI.configureMediaCache để ghi đè kích thước cache mặc định và thời gian hiệu lực. Đây là tùy chọn — nếu bạn không gọi phương thức này, các giá trị mặc định sẽ được sử dụng (100MB dung lượng đĩa, hiệu lực 7 ngày).

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

AdaptyUI.configureMediaCache(cacheConfig)

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

AdaptyUI.configureMediaCache(cacheConfig);

Tham số:

Đặt obfuscated account ID

Google Play yêu cầu obfuscated account ID cho một số trường hợp sử dụng nhất định nhằm tăng cường quyền riêng tư và bảo mật cho người dùng. Các ID này giúp Google Play xác định các giao dịch mua trong khi vẫn giữ thông tin người dùng ở dạng ẩn danh, điều này đặc biệt quan trọng cho việc ngăn chặn gian lận và phân tích dữ liệu.

Bạn có thể cần đặt các ID này nếu ứng dụng của bạn xử lý dữ liệu người dùng nhạy cảm hoặc nếu bạn bắt buộc phải tuân thủ các quy định về quyền riêng tư cụ thể. Các obfuscated ID cho phép Google Play theo dõi các giao dịch mua mà không để lộ định danh thực của người dùng.

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

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

Chạy Adapty trong một process tùy chỉnh

Mặc định, Adapty chỉ có thể chạy trong process chính của ứng dụng. Nếu ứng dụng của bạn sử dụng nhiều process, hãy khởi tạo Adapty chỉ một lần; nếu không, có thể xảy ra các hành vi không mong muốn.

Nếu bạn cần chạy Adapty trong một process khác, hãy chỉ định nó trong cấu hình của bạn:

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

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

Nếu bạn cố kích hoạt Adapty trong một tiến trình khác mà không thiết lập giá trị này, SDK sẽ ghi log cảnh báo và bỏ qua việc kích hoạt.

Bật mức độ truy cập cục bộ

Theo mặc định, mức độ truy cập cục bộ bị tắt trên Android. Để bật tính năng này, đặt withLocalAccessLevelAllowed thành true:

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

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

Khắc phục sự cố

Quy tắc sao lưu Android (Cấu hình Auto Backup)

Một số SDK (bao gồm cả Adapty) đi kèm với cấu hình Android Auto Backup riêng. Nếu bạn sử dụng nhiều SDK cùng định nghĩa quy tắc sao lưu, trình hợp nhất Android manifest có thể thất bại với lỗi liên quan đến android:fullBackupContent, android:dataExtractionRules, hoặc android:allowBackup.

Biểu hiện lỗi thường gặp: 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) Để giải quyết vấn đề này, bạn cần:

• Yêu cầu manifest merger sử dụng các giá trị của ứng dụng cho các thuộc tính liên quan đến backup.

• Gộp các quy tắc backup từ Adapty và các SDK khác vào một file XML duy nhất (hoặc một cặp file cho Android 12+).

1. Thêm namespace tools vào manifest

Nếu chưa có, hãy thêm namespace tools vào thẻ <manifest> gốc:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. Ghi đè các thuộc tính backup trong <application>

Trong file AndroidManifest.xml của app, hãy cập nhật thẻ <application> để app cung cấp các giá trị cuối cùng và yêu cầu manifest merger thay thế các giá trị của thư viện:

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

Nếu có SDK nào cũng đặt android:allowBackup, hãy thêm nó vào tools:replace:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Tạo các file backup rules đã được gộp

Tạo các file XML trong app/src/main/res/xml/ kết hợp các rule của Adapty với các rule từ các SDK khác. Android sử dụng các định dạng backup rule khác nhau tùy theo phiên bản hệ điều hành, vì vậy việc tạo cả hai file đảm bảo khả năng tương thích trên tất cả các phiên bản Android mà ứng dụng của bạn hỗ trợ.

Dành cho Android 12 trở lên (sử dụng định dạng quy tắc trích xuất dữ liệu mới):

<?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>

Đối với Android 11 và thấp hơn (sử dụng định dạng full backup content cũ):

<?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>

Với cấu hình này:

• Các quy tắc loại trừ backup của Adapty (AdaptySDKPrefs.xml) được giữ nguyên.

• Các quy tắc loại trừ của SDK khác (ví dụ: appsflyer-data) cũng được áp dụng.

• Manifest merger sử dụng cấu hình của ứng dụng và không còn bị lỗi do xung đột thuộc tính backup.

Giao dịch mua thất bại sau khi quay lại từ app khác

Nếu Activity khởi động flow mua hàng sử dụng launchMode không mặc định, Android có thể tạo lại hoặc tái sử dụng Activity đó không đúng cách khi người dùng quay lại từ Google Play, app ngân hàng, hoặc trình duyệt. Điều này có thể khiến kết quả giao dịch bị mất hoặc bị coi là đã hủy.

Để đảm bảo giao dịch mua hoạt động đúng, chỉ sử dụng standard hoặc singleTop làm launch mode cho Activity khởi động flow mua hàng, và tránh các mode khác.

Trong AndroidManifest.xml, hãy đảm bảo Activity khởi động flow mua hàng được đặt thành standard hoặc singleTop:

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